                           README.TXT file

         for Microsoft FORTRAN PowerStation 32 for Windows NT
                            Version 1.0

             (C) Copyright Microsoft Corporation, 1993

This document contains notes about using version 1.0 of the Microsoft
FORTRAN PowerStation 32 Development System for Windows NT. 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 manual.

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

This file has five parts:

     Part     Contents
     ----     --------
      1       Installation
      2       Debugging
      3       Building and Running Programs
      4       Miscellaneous
      5       Product Support in Canada


=======================< Part 1: Installation >========================

Installation and Windows NT User Accounts
-----------------------------------------
Each user account in Windows NT has a key stored in the Registry.
This key contains the user profile and privilege level set by the
system administrator. If your user account group membership
(privileges) is changed after installation, the following two
messages may appear when starting FORTRAN Visual Workbench. After
these messages appear, FORTRAN Visual Workbench starts running. 
However, when you exit you will receive the second message again.

 "The options Registry Key 'FORTRAN PowerStation' is missing. A new
  Registry Key will be created using the default settings."

 "Unable to write to the NT Registry. Option settings will not be
  saved."

The FORTRAN Visual Workbench profile information, contained in the
Microsoft FORTRAN Visual Workbench key in the Windows NT registry,
contains both program-specific information such as environment
variables and user-specific information such as Editor options. 
Each user on a Windows NT computer has a unique key for the
development environment, and that key cannot be shared on the same
machine.

Since the key cannot be shared, FORTRAN Visual Workbench must be 
installed at the user level. If your user account belongs to more
than one group (Administrators, Backup Operators, Power Users,
Users, Guests, Replicators), and you install FORTRAN Visual
Workbench by running Setup as a member of Administrators, then you
only have access to FORTRAN Visual Workbench via your FORTRAN Visual
Workbench key when you are logged in the Admin group. If you intend
to work with FORTRAN Visual Workbench as a Power User, you must
install FORTRAN Visual Workbench as a Power User, and then use
FORTRAN PowerStation as a Power User. FORTRAN Visual Workbench
functionality cannot be spanned across user groups.

To correct this situation, a user with Administrator privileges on
your machine can perform the following steps to rebuild the Registry
Key for your user account:

1. Log in as Administrator and give the User of FORTRAN PowerStation
   administrative privileges to delete the FORTRAN PowerStation entry,
   with RegEdit32 located in \winnt\system32 directory. The FORTRAN
   PowerStation entry is under HKEY_CURRENT_USER, Software, Microsoft,
   FORTRAN PowerStation. Be sure not to delete any entries other than
   FORTRAN PowerStation.

2. Remove the administrative privileges for the FORTRAN PowerStation
   User.

3. Log in as the User and start FORTRAN PowerStation again. This time
   you will only receive the first message from above and a new
   registry entry will be created.


Installation over a Network
---------------------------
You can set up FORTRAN PowerStation for installation across a network:

1) Copy all of the disks to a directory tree on the network with the
   directory names: ...\disk1, ...\disk2, and so on.

2) From the root of this directory tree, type: COPY DISK1\SETUP.*
 
3) You can now run Setup from the directory tree on the network.


Numerical Recipes and AUTOEXEC.BAT
----------------------------------
The Numerical Recipes Setup program uses the directory ...\F32\BIN as
the default location for installing the NR files. (This is the directory
used for NR in FORTRAN PowerStation 32 for MS-DOS.) If you want to
install the NR files with the rest of FORTRAN PowerStation 32 for
Windows NT, change the destination directory to ...\FPSNT\BIN.

At the end of the installation process, the NR Setup program asks if you
want it to modify the AUTOEXEC.BAT file. (This is because it is the same
program that is used to install NR under MS-DOS.) Unless you intend to
run your programs in the MS-DOS environment, you should select the
option of not updating the AUTOEXEC.BAT file.


=======================< Part 2: The Debugger >=========================

Subscript Checking on Arrays of Dimension 1
-------------------------------------------
In prior versions of Microsoft FORTRAN, debug information generated by
the /4Yb compiler option or the $DEBUG metacommand did not perform array
subscript range checking on arrays dimensioned with a dimension of 1.
This functionality has changed. Any attempt to access beyond the
declared dimension of any array will cause a run-time error if debugging
information is enabled. To disable subscript range checking for arrays
passed to subroutines, declare the dimension in the subroutine to be "*"
and not "1".


Viewing Allocatable Arrays
----------------------------
One special case of viewing variables is the Allocatable Array. Since
these arrays can be of any size, the watch window and locals window do
not allow you to expand these arrays by double-clicking on them. If you
need to view elements of the array, you can enter the individual element
you want to view into the watch window. For example, to view the 10th
element of an INTEGER array A, you would type A(10). To view the 
entire array, you can use the memory window. Use the Watch or QuickWatch 
window to determine the address of the array, then open the memory 
window and type it into the address field. Use the Options/Memory 
dialog to change the format of the memory window to the required data 
type.


MULTI Type for Symbols
----------------------
Variables that you define to be CHARACTERS, COMPLEX, or RECORD will 
appear in the local symbol table as the type MULTI. This is because
the compiler treats these variable types as multiple-byte objects.


Displaying Structure Elements in the Watch Window
-------------------------------------------------
You cannot view a single element of an array that is a member of a
structure. Instead, you must enter the name of the array itself. To
see the elements, you must expand the array. If you have an array of
structures, you can specify one structure using the FORTRAN syntax.

For example

    struc(2).element

is legal, while

    struc.element(2)

is not allowed.

The easiest way to get the information into the watch window for use in
expression evaluation is to expand the structure in the watch window,
and then copy and paste the needed information into the watch window.


Run-time Errors in the Debugger
-------------------------------
If a run-time error occurs while a program is running, the program stops
executing and all of its windows are closed. When this happens to an
application that is running in the debugger, the window in which the
application was running is closed, preventing you from reading the
run-time error message and the $DEBUG traceback (if present).

To keep the window from closing, set a breakpoint at "_exit". This
stops execution after the run-time error has been generated but before
the window is closed.


Viewing Variables in a Common Block Belonging to a DLL
------------------------------------------------------
To view the contents of a variable that is in a common block belonging
to a DLL, you must enter the context of the DLL as part of the watch
expression. For example, to specify a watch on variable X in SAMPLE.DLL,
you would enter the following watch expression:

    {,,sample.dll}X

For more information on contexts, see Help.


Using the "m" Watch Variable Format Descriptors
-----------------------------------------------
The memory watch variable formats (ma, m[b], mw, and md) do not work with 
FORTRAN expressions or variables.  However, they do work with C language 
expressions and variables, which can be used to monitor memory locations 
even if the program being debugged is entirely FORTRAN.


===============< Part 3: Building and Running Programs >================

Limit to Number of Threads for I/O
----------------------------------
A user may have up to 32 threads perform FORTRAN I/O throughout the
lifetime of a program. The 33rd thread to do I/O will cause a run-time
error. Even if a thread has been killed, it counts toward the 32 thread
maximum if it ever did I/O. There is no limit on the number of threads
that do no I/O.


Using DLL Libraries when Linking with /ML or /MT
------------------------------------------------
When using DLL libraries, the main executable should be linked with the 
/MD driver switch.  Problems can occur when linking an executable with 
/ML or /MT and using a DLL, since there would be two copies of the 
run-time libraries present in the executable. The DLL version would be 
present because DLLs are always built with /MD, and the static version 
would be present because of the /ML or /MT switch.  In this case, file 
unit numbers do not refer to the same files from within the main 
program and from within a DLL; this may also cause newlines to be 
emitted in unexpected places. These problems are avoided when linking 
with /MD because only one copy of the run-time library is in use by both
the executable and the DLL.  The only exception to the rule that /MD
should be used when linking with DLLs is when building a QuickWin
application because /MD is not permitted (see the note in QUICKWIN.TXT).

Chapter 17, "Building Programs and Libraries", states that you can use
/ML or /MT with the /LD option.  This is incorrect.  The /LD switch 
implies /MD, but the driver will no longer allow a /M option with /LD. 


Writing INTERFACE TO Statements for STDCALL Routines
----------------------------------------------------
When writing INTERFACE TO statements for procedures that use the
STDCALL calling convention, an ALIAS must be used to specify the '@num'
where the num indicates the number of bytes pushed on the stack during
the call.  If the alias string ends with an at sign (@) (with no
number), the compiler will determine the stack size for you based on
the size of the arguments in the INTERFACE TO statement. (The correct
alias name with the stack size postpended will be emitted in the
object file.)


Using MATHERRQQ
---------------
Because of performance constraints, some intrinsic functions may not
work with MATHERRQQ when you compile with optimizations for time (the
/Ox switch) enabled. MATHERRQQ does not work when linking with the DLL
versions of the FORTRAN and C run-time libraries. MATHERRQQ is also not
called for math error handling when the FORTRAN run-time library is a
DLL. To use the run-time libraries in a DLL, you must compile the main
program with the /MD switch. Finally, the default error handler for
errors from intrinsic functions cannot be replaced by MATHERRQQ in a
DLL or when a program is compiled to use the FORTRAN run-time library
in a DLL.


=======================< Part 4: Miscellaneous >========================

Floating-Point Precision: FP10.OBJ
----------------------------------
The run-time libraries set the default internal precision of the chip
(or emulator) to 64 bits. Note that this does not apply to the size of
arguments, return values, or variables; it only applies to the internal
precision at which all intermediate calculations are performed. You can
override this default and set the chip (or emulator) back to full
80-bit, 10-byte precision by linking in the FP10.OBJ file, installed by
Setup in your Fortran PowerStation LIB directory. If you are building
your application in the Visual Workbench, do the following:

1. From the Options menu, choose Project. The Project Options dialog
   box appears.

2. Choose Linker. The Linker Options dialog box appears.

3. In the Category box, select Input.

4. Type FP10.OBJ in the Object/Library Modules box.

5. Choose OK. The Project Options dialog box reappears.

6. Choose OK.

If you are running the linker from the command line, FP10.OBJ must
appear on the linker command line before any library files (.LIB).


Notes on Using NAMELIST Statement
---------------------------------
A value-assignment pair consists of a variable name, array element, or
substring followed by an equal sign and one or more values or value
separators. The equal sign can be preceded or followed by any number
of blanks, or by no blanks at all. A value separator is a single comma
or one or more blanks. Tabs are valid as white-space separators.


Using Assumed-Size Arrays of Structures
---------------------------------------
Writing an assumed-size array without specifying element indexes 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)


Reading Index before Structure Array Element
--------------------------------------------
The FORTRAN standard (p12-15) states that READ statements of the form

      READ (unit) N, A(N)

are valid, and that the value READ for N is transferred to N before
A(N) is read. This works fine for a standard array, but not when the
array is a structure element, as the following example illustrates:

      STRUCTURE /struc/
        INTEGER*2 arr(5)
      END STRUCTURE
      RECORD /struc/ st
      INTEGER*2 arr(5)
      
      OPEN(1,FILE='test.dat')
      DO WHILE (.not.eof(1))
         READ(1,*) j,arr(j)  ! The value of 'j' does transfer to
                             ! 'arr' correctly.
      ENDDO
      
      WRITE(*,*) 'Non-structure array'
      DO j=1,5
         WRITE(*,*) j,arr(j)
      ENDDO

      REWIND(1)
      DO WHILE (.not.eof(1))
         READ(1,*) j,st.arr(j)  ! The value of 'j' does not transfer
                                ! to 'st.arr' correctly.
      ENDDO

      WRITE(*,'(/1x,a)') 'Structure array'

      DO j=1,5
        WRITE(*,*) j,st.arr(j)
      ENDDO
      END  
               
The output from this program is:

Non-structure array
          1           1
          2           2
          3           3
          4           4
          5           5

Structure array
          1           2
          2           3
          3           4
          4           5
          5           0


Command Line Access to Help Files
---------------------------------
You can open and search the FORTRAN Visual Workbench help files from the
console command line by using the "fhelp" command:

Usage: fhelp [Error | Language | Compile | LInk] <search-string>

Note that you can abbreviate categories by specifying at least the
capital letters shown.

Examples:
      "fhelp error lnk1104" provides information on LINK error 1104

      "fhelp lang record" provides information on the RECORD statement

      "fhelp comp /Ox" provides information on the /Ox compiler switch

The fhelp command runs WinHelp to display the requested information
from the appropriate help file. If the search-string is not found, a
selection box is presented to further narrow the search. Note that the
search-string is optional; if it is not present, fhelp will provide a
table of contents for the selected help file.


Using Extended Characters in Console Applications
-------------------------------------------------
Because FORTRAN Visual Workbench runs in Microsoft Windows NT and
produces console applications that run in an emulation of 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 NT provides a special font called TERNIMAL that uses
the OEM character set. If you use extended characters in your files, you
need to know about both character sets.

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 the command
console, you will get the OEM representation of the characters.

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


Wrong Example Code in Reference Manual for CYCLE
------------------------------------------------
The CYCLE statement's example in the Reference Manual is incorrect. 
Help contains the correct program as CYCLE.FOR.


================< Part 5: Product Support in Canada >===================

Additional Information Regarding Support Services in Canada

Please consult Appendix G in the Programmer's guide for information on
support services in the United States.

Microsoft Download Service
--------------------------
Access, via modem, the Driver Library and the most current technical
notes (1200, 2400, or 9600 baud; no parity; 8 data bits; 1 stop bit).
In Canada, call (905) 507-3022.

Standard Support
----------------
In Canada, support engineers are available via a toll call between
8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding
holidays. Call (905) 568-3503. This support is available for 90 days
after you make your first call.

Priority Support
----------------
The Microsoft Support Network offers priority telephone access to
Microsoft support engineers 24 hours a day, 7 days a week, except
holidays. 

In Canada, call (800) 668-7975 for more information.

Text Telephone
--------------
Microsoft text telephone (TT/TDD) services are available for the deaf
or hard of hearing. In Canada, using a TT/TDD modem, dial
(905) 568-9641 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday
through Friday, excluding holidays.

Other Support Options
---------------------
The Microsoft Support Network offers annual and multiple incident
support plans. In Canada, call (800) 668-7975 between 8:00 A.M. and
8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

Product Training and Consultation
---------------------------------
Microsoft Solution Providers are independent organizations that provide
consulting, integration, customization, development, technical support
and training, and other services for Microsoft products. These companies
are called Solution Providers because they apply technology and provide
services to help solve real-world problems.  In Canada, call
(800) 668-7975 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday
through Friday, excluding holidays.

========================================================================

