Index of Topics

- " -

The "NO87" Environment Variable

- 1 -

16-bit:  A Subprogram that Never Returns
16-bit:  Alias Names
16-bit:  Alternate Method of Passing Character Arguments
16-bit:  Alternate Names for Symbols
16-bit:  Assembly Language Considerations
16-bit:  Auxiliary Pragmas
16-bit:  Auxiliary Pragmas and the 80x87
16-bit:  Calling Conventions
16-bit:  Character Functions
16-bit:  Code Models
16-bit:  Data Models
16-bit:  Defining Exported Symbols in Dynamic Link Libraries
16-bit:  Defining Windows Callback Functions
16-bit:  Describing Argument Information
16-bit:  Describing Calling Information
16-bit:  Describing How Subprograms Use Variables in Common
16-bit:  Describing Subprogram Return Information
16-bit:  Describing the Registers Modified by a Subprogram
16-bit:  Forcing Arguments into Specific Registers
16-bit:  Linking Applications for the Various Memory Models
16-bit:  Loading Data Segment Register
16-bit:  Memory Layout
16-bit:  Memory Models
16-bit:  Mixed Memory Model
16-bit:  Passing Arguments in Registers
16-bit:  Passing Arguments in Reverse Order
16-bit:  Passing Arguments to In-Line Subprograms
16-bit:  Passing Arguments to non-FORTRAN Subprograms
16-bit:  Pragmas
16-bit:  Predefined "__cdecl" Alias
16-bit:  Predefined "__pascal" Alias
16-bit:  Predefined "__watcall" Alias
16-bit:  Predefined Aliases
16-bit:  Preserving 80x87 Floating-Point Registers Across Calls
16-bit:  Processing Alternate Returns
16-bit:  Processing Function Return Values Using an 80x87
16-bit:  Processing Function Return Values with no 80x87
16-bit:  Removing Arguments from the Stack
16-bit:  Returning Floating-Point Data
16-bit:  Returning Structures and Complex Numbers
16-bit:  Returning Subprogram Values in Registers
16-bit:  Returning Values from Assembly Language Functions
16-bit:  Specifying Symbol Attributes
16-bit:  Summary of Memory Models
16-bit:  Using the 80x87 to Pass Arguments
16-bit:  Using the 80x87 to Return Subprogram Values
16-bit:  Writing Assembly Language Subprograms

- 3 -

32-bit:  A Subprogram that Never Returns
32-bit:  Alias Names
32-bit:  Alternate Method of Passing Character Arguments
32-bit:  Alternate Names for Symbols
32-bit:  Assembly Language Considerations
32-bit:  Auxiliary Pragmas
32-bit:  Auxiliary Pragmas and the 80x87
32-bit:  Calling Conventions
32-bit:  Character Functions
32-bit:  Code Models
32-bit:  Data Models
32-bit:  Defining Exported Symbols in Dynamic Link Libraries
32-bit:  Describing Argument Information
32-bit:  Describing Calling Information
32-bit:  Describing How Subprograms Use Variables in Common
32-bit:  Describing Subprogram Return Information
32-bit:  Describing the Registers Modified by a Subprogram
32-bit:  Flat Memory Model
32-bit:  Forcing Arguments into Specific Registers
32-bit:  Linking Applications for the Various Memory Models
32-bit:  Loading Data Segment Register
32-bit:  Memory Layout
32-bit:  Memory Models
32-bit:  Mixed Memory Model
32-bit:  Passing Arguments in Registers
32-bit:  Passing Arguments in Reverse Order
32-bit:  Passing Arguments to In-Line Subprograms
32-bit:  Passing Arguments to non-FORTRAN Subprograms
32-bit:  Pragmas
32-bit:  Predefined "__cdecl" Alias
32-bit:  Predefined "__pascal" Alias
32-bit:  Predefined "__stdcall" Alias
32-bit:  Predefined "__syscall" Alias
32-bit:  Predefined "__watcall" Alias (register calling convention)
32-bit:  Predefined "__watcall" Alias (stack calling convention)
32-bit:  Predefined Aliases
32-bit:  Preserving 80x87 Floating-Point Registers Across Calls
32-bit:  Processing Alternate Returns
32-bit:  Processing Function Return Values Using an 80x87
32-bit:  Processing Function Return Values with no 80x87
32-bit:  Removing Arguments from the Stack
32-bit:  Returning Floating-Point Data
32-bit:  Returning Structures and Complex Numbers
32-bit:  Returning Subprogram Values in Registers
32-bit:  Returning Values from Assembly Language Functions
32-bit:  Specifying Symbol Attributes
32-bit:  Stack-Based Calling Convention
32-bit:  Summary of Memory Models
32-bit:  Using the 80x87 to Pass Arguments
32-bit:  Using the 80x87 to Return Subprogram Values
32-bit:  Using the Stack-Based Calling Convention
32-bit:  Writing Assembly Language Subprograms

- A -

About This Manual
Attributes of Files

- C -

CHARACTER Data Type
Compiler Diagnostics
Compiler Options
Compiler Options Relating to Floating-point
COMPLEX*16 Data Type
COMPLEX, COMPLEX*8, and DOUBLE COMPLEX Data Types

- D -

Data Representation On x86-based Platforms
Debugging statements ("D" in Column 1)
Default Windowing Functions
The DEFINE Compiler Directive
DOUBLE PRECISION and REAL*8 Data Types
dwfDeleteOnClose
dwfSetAboutDlg
dwfSetAppTitle
dwfSetConTitle
dwfShutDown
dwfYield

- E -

The EJECT Compiler Directive
The ELSE Compiler Directive
The ELSEIFDEF and ELSEIFNDEF Compiler Directive
Establishing Connections Between Units and Files
Examples of FAT File Specifications
Examples of HPFS File Specifications

- F -

File Handling Defaults
File Names in the FAT File System
File Names in the High Performance File System
File Sharing
Files with no Record Structure
FINCLUDE
Floating-point Accuracy On x86-based Platforms
Floating-point Exception Handling
Floating-point Exceptions On x86-based Platforms
FORMATTED Records
Functions IARGC and IGETARG

- G -

General Notes About Compiler Directives

- I -

The IFDEF, IFNDEF and ENDIF Compiler Directive
The INCLUDE Compiler Directive
Input/Output Buffer Size
INTEGER and INTEGER*4 Data Types
INTEGER Function FGETCMD
INTEGER Function FGETENV
INTEGER Function FILESIZE
INTEGER Function FLUSHUNIT
INTEGER Function FNEXTRECL
INTEGER Function FSIGNAL
INTEGER Function FSPAWN
INTEGER Function FSYSTEM
INTEGER Function GROWHANDLES
INTEGER Function SEEKUNIT
INTEGER Function SETJMP/Subroutine LONGJMP
INTEGER Function SETSYSHANDLE
INTEGER*1 Data Type
INTEGER*2 Data Type
INTEGER*2 Function SYSHANDLE

- L -

LFN
LIB
LIBDOS
LIBOS2
LIBPHAR
LIBWIN
LOGICAL and LOGICAL*4 Data Types
Logical File Name Support
LOGICAL*1 Data Type

- M -

Math Error Functions

- N -

NO87

- O -

Open Watcom F77 Options Summary
The Open Watcom F77 Subprogram Library
Open Watcom FORTRAN 77 80x87 Emulator Libraries
Open Watcom FORTRAN 77 Command Line Examples
Open Watcom FORTRAN 77 Command Line Format
The Open Watcom FORTRAN 77 Compiler
Open Watcom FORTRAN 77 Compiler Directives
Open Watcom FORTRAN 77 Compiler Options
Open Watcom FORTRAN 77 File Handling
Open Watcom FORTRAN 77 INCLUDE File Processing
The Open Watcom FORTRAN 77 Libraries

- P -

PATH
The PRAGMA Compiler Directive
A Preconnection Tutorial
Print File Attributes
Printer Device Support

- R -

REAL and REAL*4 Data Types
REAL Function URAND
Record Access
Record Format
Record Size
Record Type

- S -

Serial Device Support
Special DOS Device Names
Special OS/2 Device Names
Storage Organization of Data Types
Subroutine FEXIT
Subroutine FINTR and FINTRF
Subroutine FTRACEBACK
Subroutine GETDAT
Subroutine GETTIM

- T -

Terminal or Console Device Support
TMP

- U -

The UNDEFINE Compiler Directive
UNFORMATTED Records
Use of Environment Variables

- W -

WATCOM
WCGMEMORY
WCL
WCL386
WD
WDW
WFC
WFC/WFC386 Environment Variables
WFC386
WFL
WFL386
WLANG

About This Manual

Chapter 1 -

About This Manual.
This chapter provides an overview of the contents of this guide.

Chapter 2 -

Open Watcom FORTRAN 77 Compiler Options.
This chapter also provides a summary and reference section for the valid compiler options.

Chapter 3 -

The Open Watcom FORTRAN 77 Compiler.
This chapter describes how to compile an application from the command line, describes compiler environment variables, provides examples of command line use of the compiler, and and describes compiler diagnostics.

Chapter 4 -

The Open Watcom FORTRAN 77 Libraries.
This chapter describes the Open Watcom FORTRAN 77 run-time libraries.

Chapter 5 -

Open Watcom FORTRAN 77 Compiler Directives.
This chapter describes compiler directives including INCLUDE file processing.

Chapter 6 -

Open Watcom FORTRAN 77 File Handling.
This chapter describes run-time file handling.

Chapter 7 -

The Open Watcom F77 Subprogram Library.
This chapter describes subprograms available for special operations.

Chapter 8 -

16-bit:  Memory Models.
This chapter describes the Open Watcom FORTRAN 77 memory models (including code and data models), the tiny memory model, the mixed memory model, linking applications for the various memory models, creating a tiny memory model application, and memory layout in an executable.

Chapter 9 -

16-bit:  Assembly Language Considerations.
This chapter describes issues relating to 16-bit interfacing such as parameter passing conventions.

Chapter 10 -

16-bit:  Pragmas.
This chapter describes the use of pragmas with the 16-bit compilers.

Chapter 11 -

32-bit:  Memory Models.
This chapter describes the Open Watcom FORTRAN 77 memory models (including code and data models), the flat memory model, the mixed memory model, linking applications for the various memory models, and memory layout in an executable.

Chapter 12 -

32-bit:  Assembly Language Considerations.
This chapter describes issues relating to 32-bit interfacing such as parameter passing conventions.

Chapter 13 -

32-bit:  Pragmas.
This chapter describes the use of pragmas with the 32-bit compilers.

Appendix A.  -

Use of Environment Variables.
This appendix describes all the environment variables used by the compilers and related tools.

Open Watcom FORTRAN 77 Compiler Options

Open Watcom F77 Options Summary

Compiler options:

Description:

0

(16-bit only) assume 8088/8086 processor

1

(16-bit only) assume 188/186 processor

2

(16-bit only) assume 286 processor

3

assume 386 processor

4

assume 486 processor

5

assume Pentium processor

6

assume Pentium Pro processor

[NO]ALign

align COMMON segments

[NO]AUtomatic

all local variables on the stack

BD

(32-bit only) dynamic link library

BM

(32-bit only) multithread application

[NO]BOunds

generate subscript bounds checking code

BW

(32-bit only) default windowed application

[NO]CC

carriage control recognition requested for output devices such as the console

CHInese

Chinese character set

[NO]COde

constants in code segment

D1

include line # debugging information

D2

include full debugging information

[NO]DEBug

perform run-time checking

DEFine=<macro>

define macro

[NO]DEPendency

generate file dependencies

[NO]DEScriptor

pass character arguments using string descriptor

DIsk

write listing file to disk

DT=<size>

set data threshold

[NO]ERrorfile

generate an error file

[NO]EXPlicit

declare type of all symbols

[NO]EXtensions

issue extension messages

[NO]EZ

(32-bit only) Easy OMF-386 object files

FO=<obj_default>

set default object file name

[NO]FORmat

relax format type checking

FPC

generate calls to floating-point library

FPD

enable generation of Pentium FDIV bug check code

FPI

generate inline 80x87 instructions with emulation

FPI87

generate inline 80x87 instructions

FPR

floating-point backward compatibility

FP2

generate inline 80x87 instructions

FP3

generate inline 80387 instructions

FP5

optimize floating-point for Pentium

FP6

optimize floating-point for Pentium Pro

[NO]FSfloats

FS not fixed

[NO]GSfloats

GS not fixed

HC

Codeview debugging information

HD

DWARF debugging information

HW

Open Watcom debugging information

[NO]INCList

write content of INCLUDE files to listing

INCPath=[d:]path

[d:]path...  path for INCLUDE files

[NO]IPromote

promote INTEGER*1 and INTEGER*2 arguments to INTEGER*4

Japanese

Japanese character set

KOrean

Korean character set

[NO]LFwithff

LF with FF

[NO]LIBinfo

include default library information in object file

[NO]LISt

generate a listing file

[NO]MAngle

mangle COMMON segment names

MC

(32-bit only) compact memory model

MF

(32-bit only) flat memory model

MH

(16-bit only) huge memory model

ML

large memory model

MM

medium memory model

MS

(32-bit only) small memory model

OB

(32-bit only) base pointer optimizations

OBP

branch prediction

OC

do not convert "call" followed by "ret" to "jmp"

OD

disable optimizations

ODO

DO-variables do not overflow

OF

always generate a stack frame

OH

enable repeated optimizations (longer compiles)

OI

generate statement functions in-line

OK

enable control flow prologues and epilogues

OL

perform loop optimizations

OL+

perform loop optimizations with loop unrolling

OM

generate floating-point 80x87 math instructions in-line

ON

numeric optimizations

OP

precision optimizations

OR

instruction scheduling

OS

optimize for space

OT

optimize for time

OX

equivalent to OBP, ODO, OI, OK, OL, OM, OR, and OT (16-bit) or OB, OBP, ODO, OI, OK, OL, OM, OR, and OT (32-bit)

PRint

write listing file to printer

[NO]Quiet

operate quietly

[NO]Reference

issue unreferenced warning

[NO]RESource

messages in resource file

[NO]SAve

SAVE local variables

[NO]SC

(32-bit only) stack calling convention

[NO]SEpcomma

allow comma separator in formatted input

[NO]SG

(32-bit only) automatic stack growing

[NO]SHort

set default INTEGER/LOGICAL size to 2/1 bytes

[NO]SR

save/restore segment registers

[NO]SSfloats

(16-bit only) SS is not default data segment

[NO]STack

generate stack checking code

[NO]SYntax

syntax check only

[NO]TErminal

messages to terminal

[NO]TRace

generate code for run-time traceback

TYpe

write listing file to terminal

[NO]WArnings

issue warning messages

[NO]WILd

relax wild branch checking

[NO]WIndows

(16-bit only) compile code for Windows

[NO]XFloat

extend floating-point precision

[NO]XLine

extend line length to 132

0

16-bit only

5

32-bit only

ALign

NOAUtomatic

NOBOunds

NOCC

NOCOde

NODEBug

DEPendency

DEScriptor

DT=256

ERrorfile

NOEXPlicit

NOEXtensions

NOEZ

32-bit only

NOFORmat

FPI

FP2

16-bit only

FP3

32-bit only

NOFPD

FSfloats

all but flat memory model

NOFSfloats

flat memory model only

GSfloats

NOINCList

NOIPromote

NOLFwithff

LIBinfo

NOLISt

NOMAngle

ML

16-bit only

MF

32-bit only

NOQuiet

Reference

NORESource

NOSAve

NOSC

32-bit only

NOSEpcomma

NOSG

32-bit only

NOSHort

NOSR

NOSSfloats

16-bit only

NOSTack

NOSYntax

TErminal

NOTRace

WArnings

NOWILd

NOWIndows

16-bit only

NOXFloat

NOXLine

Compiler Options

Option:

Description:

0

(16-bit only) Open Watcom F77 will make use of only 8088/8086 instructions in the generated object code.  The resulting code will run on 8086 and all upward compatible processors.  This is the default option for the 16-bit compiler.

1

(16-bit only) Open Watcom F77 will make use of 188/186 instructions in the generated object code whenever possible.  The resulting code probably will not run on 8086 compatible processors but it will run on 186 and all upward compatible processors.

2

(16-bit only) Open Watcom F77 will make use of 286 instructions in the generated object code whenever possible.  The resulting code probably will not run on 8086 or 186 compatible processors but it will run on 286 and all upward compatible processors.

3

Open Watcom F77 will assume a 386 processor and will generate instructions based on 386 instruction timings.

4

Open Watcom F77 will assume a 486 processor and will generate 386 instructions based on 486 instruction timings.  The code is optimized for 486 processors rather than 386 processors.

5

Open Watcom F77 will assume a Pentium processor and will generate 386 instructions based on Pentium instruction timings.  The code is optimized for Pentium processors rather than 386 processors.  This is the default option for the 32-bit compiler.

6

Open Watcom F77 will assume a Pentium Pro processor and will generate 386 instructions based on Pentium Pro instruction timings.   The code is optimized for Pentium Pro processors rather than 386 processors.

[NO]ALign

The "align" option tells the compiler to allocate all COMMON blocks on paragraph boundaries (multiples of 16).  If you do not want COMMON blocks to be aligned, specify "noalign".  The default is "align".

[NO]AUtomatic

The "automatic" option tells the compiler to allocate all local variables, including arrays, on the stack.  This is particularly useful for recursive functions or subroutines that require a new set of local variables to be allocated for each recursive invocation.  Note that the "automatic" option may significantly increase the stack requirements of your application.  You can increase your stack size by using the "STACK" option when you link your application.

BD

(32-bit only, OS/2 and Windows NT only) This option causes the compiler to imbed the appropriate DLL library name in the object file and to include the appropriate DLL initialization code sequence when the application is linked.

BM

(32-bit only, OS/2 and Windows NT only) This option causes the compiler to imbed the appropriate multi-thread library name in the object file.

[NO]BOunds

The "bounds" option causes the generation of code that performs array subscript and character substring bounds checking.   Note that this option may significantly reduce the performance of your application but is an excellent way to eliminate many programming errors.  The default option is "nobounds".

BW

(OS/2, Windows 3.x, and Windows NT only) This option causes the compiler to import a special symbol so that the default windowing library code is linked into your application.

[NO]CC

The "cc" option specifies that the output to devices contains carriage control information that is to be interpreted appropriately for the output device (e.g., console device).  ASA carriage control characters are converted to ASCII vertical spacing control characters.  Note that a blank carriage control character will automatically be generated for list-directed output and will be interpreted as a single-line spacing command.

CHInese

This option is part of the national language support provided by Open Watcom F77.  It instructs the compiler that the source code contains characters from the Traditional Chinese character set.  This includes double-byte characters.  This option enables the use of Chinese variable names.  The compiler's run-time system will ensure that character strings are not split in the middle of a double-byte character when output spans record boundaries (as can happen in list-directed output).

[NO]COde

The "code" option causes the code generator to place character and numeric constants in code segment.  Data generated for FORMAT statements will also be placed in the code segment.  The default option is "nocode".

D1

Line number information is included in the object file ("type 1 debugging information").  This option provides additional information to Open Watcom Debugger (at the expense of larger object files and executable files).  Line numbers are handy when debugging your application with Open Watcom Debugger.

D2

In addition to line number information, local symbol and data type information is included in the object file ("type 2 debugging information").  Although global symbol information can be made available to Open Watcom Debugger through a Open Watcom Linker option, local symbol and typing information must be requested when the source file is compiled.  This option provides additional information to Open Watcom Debugger (at the expense of larger object files and executable files).  However, it will make the debugging chore somewhat easier.

[NO]DEBug

The "debug" option causes the generation of run-time checking code.  This includes subscript and substring bounds checking as well as code that allows a run-time traceback to be issued when an error occurs.  The default option is "nodebug".

DEFine=<macro>

This option is equivalent to specifying the following "define" compiler directive.
     
     *$define <macro>

The macro specified by the "define" option or compiler directive becomes defined.  The definition status of the specified macro can be checked using the "ifdef", "ifndef", "elseifdef" or "elseifndef" compiler directives.  This allows source code to be conditionally compiled depending on the definition status of the macro. 

The macro __i86__ is a special macro that is defined by the compiler and identifies the target as a 16-bit Intel 80x86 compatible environment.

The macro __386__ is a special macro that is defined by the compiler and identifies the target as a 32-bit Intel 386 compatible environment.

The macro __stack_conventions__ is a special macro that is defined by the 32-bit compiler when the "sc" compiler option is specified to indicate that stack calling conventions are to be used for code generation.

The macro __fpi__ is a special macro that is defined by the compiler when one of the following floating-point options is specified:  "fpi" or "fpi87".

[NO]DEPendency

The "dependency" option specifies that file dependencies are to be included in the object file.  This is the default option.  This option is used by the Open Watcom Integrated Development Environment to determine if an object file is up-to-date with respect to the source files used to build it.  You can specify the "nodependency" option if you do not want file dependencies to be included in the object file.

[NO]DEScriptor

The "descriptor" option specifies that string descriptors are to be passed for character arguments.  This is the default option.  You can specify the "nodescriptor" option if you do not want string descriptors to be passed for character arguments.  Instead, the pointer to the actual character data and the length will be passed as two arguments.  The arguments for the length will be passed as additional arguments following the normal argument list.   For character functions, the pointer to the data and the length of the character function will be passed as the first two arguments.

DIsk

When this option is used in conjunction with the "list" option, the listing file is written to the current directory of the default disk.  The listing file name will be the same as the source file name but the file extension will be .lst.  By default, listing files are written to disk.  The "disk" option will override any previously specified "type" or "print" option.

DT=<size>

The "data threshold" option is used to set the minimum size for data objects to be included in the default data segment.  Normally, all data objects smaller than 256 bytes in size are placed in the default data segment.  When there is a large amount of static data, it is often useful to set the data threshold size so that all objects of the specified size or larger are placed into another segment.  For example, the option:
     
     -DT=100

causes all data objects of 100 bytes or more to be placed in a far data segment.  The "data threshold" only applies to the large and huge memory models where there can be more than one data segment.  The default data threshold value is 256.

[NO]ERrorfile

This option is used to control whether error messages are output to a separate error file.  The error file is a disk file of type .err and is produced if any diagnostic messages are issued by the compiler.  Specifying "noerrorfile" prevents the creation of an error file.  By default, an error file is created.
If an error file exists before compilation begins, it will be erased.  If no diagnostic messages are produced then an error file will not be created even though the "errorfile" option is selected.  This option has no effect on the inclusion of diagnostic messages in the source listing file or the production of diagnostic messages on the screen.

[NO]EXPlicit

The "explicit" option requires the type of all symbols to be explicitly declared.  An error message will be issued by the compiler if a symbol that does not appear in a type declaration statement is encountered.  Specifying this option is equivalent to using the IMPLICIT NONE statement.  By default, symbols do not have to be explicitly typed.

[NO]EXtensions

This option is used to control the printing of extension messages.  This option may be specified on the command line or it may be placed anywhere in the source input stream.  In a source file, the option appears as a comment line and takes the following form.
     
     *$[NO]EXtensions

The "extensions" option enables the printing of extension messages, while "noextensions" disables the printing of these messages.  By default, extension messages are not printed.

[NO]EZ

(32-bit only) Open Watcom F77 will generate an object file in Phar Lap Easy OMF-386 (object module format) instead of the default Microsoft OMF.  The default option is "noez".

FO=<obj_default>

By default, the object file name is constructed from the source file name.  Using the "fo" option, the default object file drive, path, file name and extension can be specified.
Example:

     C>wfc386 report -fo=d:\programs\obj\

A trailing "\" must be specified for directory names.  If, for example, the option was specified as "-fo=d:\programs\obj" then the object file would be called D:\PROGRAMS\OBJ.OBJ.

A default extension must be preceded by a period (".").

Example:

     C>wfc386 report -fo=d:\programs\obj\.dbo

[NO]FORmat

The "format" option suppresses the run-time checking that ensures that the type of an input/output list item matches the format edit descriptor in a format specification.  This allows an input/output list item of type INTEGER to be formatted using an F, E or D edit descriptor.  It also allows an input/output list item of a floating-point type to be formatted using an I edit descriptor.  Normally, this generates an error.  The "format" option is particularly useful for applications that use integer arrays to store integer and floating-point data.  The default option is "noformat".

FPC

All floating-point arithmetic is done with calls to a floating-point emulation library.  This option should be used when speed of floating-point emulation is favoured over code size.

FPI

(16-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the object code for floating-point operations.  Depending on which library the code is linked against, these instructions will be left as is or they will be replaced by special interrupt instructions.  In the latter case, floating-point will be emulated if an 80x87 is not present.  This is the default floating-point option if none is specified.
(32-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the object code for floating-point operations.  When any module containing floating-point operations is compiled with the "fpi" option, coprocessor emulation software will be included in the application when it is linked.  Thus, an 80x87 coprocessor need not be present at run-time.  This is the default floating-point option if none is specified.

FPI87

(16-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the object code for floating-point operations.  An 80x87 coprocessor must be present at run-time.  If the "2" option is used in conjunction with this option, Open Watcom F77 will generate 287/387 compatible instructions; otherwise Open Watcom F77 will generate 8087 compatible instructions.
(32-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the object code for floating-point operations.  When the "fpi87" option is used exclusively, coprocessor emulation software is not included in the application when it is linked.  A 80x87 coprocessor must be present at run-time. 

16-bit Notes:

1. When any module in an application is compiled with a particular "floating-point" option, then all modules must be compiled with the same option.
2. Different math libraries are provided for applications which have been compiled with a particular floating-point option.   See the chapter entitled The Open Watcom FORTRAN 77 Libraries.

32-bit Notes:

1. When any module in an application is compiled with the "fpc" option, then all modules must be compiled with the "fpc" option.
2. When any module in an application is compiled with the "fpi" or "fpi87" option, then all modules must be compiled with one of these two options.
3. If you wish to have floating-point emulation software included in the application, you should select the "fpi" option.  A 387 coprocessor need not be present at run-time.
4. Different math libraries are provided for applications which have been compiled with a particular floating-point option.   See the chapter entitled The Open Watcom FORTRAN 77 Libraries.

FP2

Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the object code for floating-point operations.   For Open Watcom compilers generating 16-bit, this is the default.  For 32-bit applications, use this option if you wish to support those few 386 systems that are equipped with an 80287 numeric data processor ("fp3" is the default for Open Watcom compilers generating 32-bit code).  However, for 32-bit applications, the use of this option will reduce execution performance.

FP3

Open Watcom F77 will generate in-line 387-compatible numeric data processor instructions into the object code for floating-point operations.  For 16-bit applications, the use of this option will limit the range of systems on which the application will run but there are execution performance improvements.

FP5

Open Watcom F77 will generate in-line 387-compatible numeric data processor instructions into the object code for floating-point operations.  The sequence of floating-point instructions will be optimized for greatest possible performance on the Intel Pentium processor.  For 16-bit applications, the use of this option will limit the range of systems on which the application will run but there are execution performance improvements.

FP6

Open Watcom F77 will generate in-line 387-compatible numeric data processor instructions into the object code for floating-point operations.  The sequence of floating-point instructions will be optimized for greatest possible performance on the Intel Pentium Pro processor.  For 16-bit applications, the use of this option will limit the range of systems on which the application will run but there are execution performance improvements.

[NO]FPD

A subtle problem was detected in the FDIV instruction of Intel's original Pentium CPU.  In certain rare cases, the result of a floating-point divide could have less precision than it should.  Contact Intel directly for more information on the issue.
As a result, the run-time system startup code has been modified to test for a faulty Pentium.  If the FDIV instruction is found to be flawed, the low order bit of the run-time system variable __chipbug will be set.

If the FDIV instruction does not show the problem, the low order bit will be clear.  If the Pentium FDIV flaw is a concern for your application, there are two approaches that you could take:

1. You may test the __chipbug variable in your code in all floating-point and memory models and take appropriate action (such as display a warning message or discontinue the application).
2. Alternately, you can use the "fpd" option when compiling your code.  This option directs the compiler to generate additional code whenever an FDIV instruction is generated which tests the low order bit of __chipbug and, if on, calls the software workaround code in the math libraries.  If the bit is off, an in-line FDIV instruction will be performed as before.

If you know that your application will never run on a defective Pentium CPU, or your analysis shows that the FDIV problem will not affect your results, you need not use the "fpd" option.

FPR

Use this option if you want to generate floating-point instructions that will be compatible with version 9.0 or earlier of the compilers.  For more information on floating-point conventions see the sections entitled 16-bit:  Using the 80x87 to Pass Arguments and 32-bit:  Using the 80x87 to Pass Arguments.

[NO]FSfloats

The "fsfloats" option enables the use of the FS segment register in the generated code.  This is the default for all but the flat memory model.  In the flat memory model, the default is "nofsfloats" (the FS segment register is not used in the generated code).

[NO]GSfloats

The "gsfloats" option enables the use of the GS segment register in the generated code.  This is the default.   If you would like to prevent the use of the GS segment register in the the generated code, specify the "nogsfloats" option.

HC

The type of debugging information that is to be included in the object file is "Codeview".  The default type of debugging information is "Dwarf" (HD).  If you wish to use the Microsoft Codeview debugger, then choose the "HC" option.  When linking the application, you must also choose the appropriate Open Watcom Linker DEBUG directive.  See the Open Watcom Linker User's Guide for more information.

HD

The type of debugging information that is to be included in the object file is "Dwarf".  This is the default type of debugging information.  If you wish to use the Microsoft Codeview debugger, then choose the "HC" option.   When linking the application, you must also choose the appropriate Open Watcom Linker DEBUG directive.  See the Open Watcom Linker User's Guide for more information.

HW

The type of debugging information that is to be included in the object file is "Open Watcom".  The default type of debugging information is "Dwarf" (HD).  If you wish to use the Microsoft Codeview debugger, then choose the "HC" option.  When linking the application, you must also choose the appropriate Open Watcom Linker DEBUG directive.  See the Open Watcom Linker User's Guide for more information.

[NO]INCList

This option is used to control the listing of the contents of INCLUDE files to the listing file.  The "inclist" option enables the listing of INCLUDE files, while "noinclist" disables the listing of these files.  The default option is "noinclist".

INCPath=[d:]path

[d:]path...  This option is used to specify directories that are to be searched for include files.  Each path is separated from the previous by a semicolon (";").  These directories are searched in the order listed before those in the FINCLUDE environment variable.

[NO]IPromote

The "ipromote" option causes the compiler to promote the INTEGER*1 and INTEGER*2 arguments of some INTEGER*4 intrinsics without issuing an error diagnostic.  This allows code such as the following to be compiled without error:
Example:

         INTEGER I*1, J*2
         I = 1
         J = 2
         PRINT *, IDIM( I, J )
         END

This works for the following intrinsic functions:  ABS(), IABS(), DIM(), IDIM(), SIGN(), ISIGN(), MAX(), AMAX0(), MAX0(), MIN(), AMIN0(), and MIN0().  When the "ipromote" option is specified, all integer arguments that are passed to these functions are promoted to INTEGER*4.

Japanese

This option is part of the national language support provided by Open Watcom F77.  It instructs the compiler that the source code contains characters from the Japanese character set.  This includes double-byte characters.  This option enables the use of Japanese variable names.  The compiler's run-time system will ensure that character strings are not split in the middle of a double-byte character when output spans record boundaries (as can happen in list-directed output).

KORean

This option is part of the national language support provided by Open Watcom F77.  It instructs the compiler that the source code contains characters from the Korean character set.  This includes double-byte characters.  This option enables the use of Korean variable names.  The compiler's run-time system will ensure that character strings are not split in the middle of a double-byte character when output spans record boundaries (as can happen in list-directed output).

[NO]LFwithff

This option is used to control whether a line-feed character (LF=CHAR(10)) is to be emitted before a form-feed character (FF=CHAR(12)) is emitted.  This option applies to carriage control handling.  Normally, the run-time system will emit only a form-feed character to cause a page eject when the ASA control character "1" is found in the first column of a record.  The "lfwithff" option will cause the run-time system to emit a line-feed character and then a form-feed character.
The "lfwithff" option will have little effect on printers, but it will change the appearance of output to the screen by eliminating overwritten text when form-feed characters are not handled by the output device.  The default option is "nolfwithff".

[NO]LIBinfo

This option is used to control the inclusion of default library information in the object file.  The "libinfo" option enables the inclusion of default library information, while "nolibinfo" disables the inclusion of this information.   The default option is "libinfo".

[NO]LISt

This option may be specified on the command line or it may be placed anywhere in the source input stream.  On the command line, this option is used to control the creation of a listing file.  The "list" option causes a listing file to be created while "nolist" requests that no listing file be created.  The default option is "nolist".
In a source file, the option appears as a comment line and takes the following form.

     
     *$[NO]LISt

Specifying *$LIST causes the source lines that follow this option to be listed in the source listing file while *$NOLIST disables the listing of the source lines that follow.  This option cannot appear on the same source line with other options.

[NO]MAngle

This option is used to alter COMMON block segment and class names.
Example:

           REAL R, S
           COMMON /BLK/ R, S
           END

For a named COMMON block called "BLK", the default convention is to name the segment "BLK" and the class "BLK".

     
     BLK             SEGMENT PARA COMMON USE32 'BLK'

When you use the "mangle" option, the segment is named "_COMMON_BLK" and the class is named "_COMMON_BLK_DATA".

     
     _COMMON_BLK     SEGMENT PARA COMMON USE32 '_COMMON_BLK_DATA'

MC

(32-bit only) The "compact" memory model (small code, big data) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.

MF

(32-bit only) The "flat" memory model (code and data up to 4 gigabytes) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.  This is the default memory model option.

MH

(16-bit only) The "huge" memory model (big code, huge data) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.

ML

The "large" memory model (big code, big data) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.   This is the default 16-bit memory model option.

MM

The "medium" memory model (big code, small data) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.

MS

(32-bit only) The "small" memory model (small code, small data) is selected.  The various models supported by Open Watcom F77 are described in the chapters entitled 16-bit:  Memory Models and 32-bit:  Memory Models.

OB

(32-bit only) This option allows the use of the ESP register as a base register to reference local variables and subprogram arguments in the generated code.  This can reduce the size of the prologue/epilogue sequences generated by the compiler thus improving overall performance.  Note that when this option is specified, the compiler will abort when there is not enough memory to optimize the subprogram.  By default, the code generator uses more memory-efficient algorithms when a low-on-memory condition is detected.

OBP

This option causes the code generator to try to order the blocks of code emitted such that the "expected" execution path (as determined by a set of simple heuristics) will be straight through, with other cases being handled by jumps to separate blocks of code "out of line".  This will result in better cache utilization on the Pentium.  If the heuristics do not apply to your code, it could result in a performance decrease.

OC

This option may be used to disable the optimization where a "CALL" followed by a "RET" (return) is changed into a "JMP" (jump) instruction.  This option is required if you wish to link an overlayed program using the Microsoft DOS Overlay Linker.  The Microsoft DOS Overlay Linker will create overlay calls for a "CALL" instruction only.  This option is not required when using the Open Watcom Linker.  This option is not assumed by default.

OD

Non-optimized code sequences are generated.  The resulting code will be much easier to debug when using Open Watcom Debugger.   By default, Open Watcom F77 will select "od" if "d2" is specified.

ODO

Optimized DO-loop iteration code is generated.  Caution should be exercised with the use of this option since the case of an iterating value overflowing is assumed to never occur.  The following example should not be compiled with this option since the terminal value of IX wraps from a positive integer to a negative integer.
Example:

         INTEGER*2 IX
         DO IX=32766,32767
             .
             .
             .
         ENDDO

The values of IX are 32766, 32767, -32768, -32767, ...  since IX is INTEGER*2 (a 16-bit signed value) and it never exceeds the terminal value.

OF

This option selects the generation of traceable stack frames for those functions that contain calls or require stack frame setup.  To use Open Watcom's "Dynamic Overlay Manager" (DOS only), you must compile all modules using the "of" option.  For near functions, the following function prologue sequence is generated.
16-bit:

     
         push BP
         mov  BP,SP

32-bit:

     
         push EBP
         mov  EBP,ESP

For far functions, the following function prologue sequence is generated.

16-bit:

     
         inc  BP
         push BP
         mov  BP,SP

32-bit:

     
         inc  EBP
         push EBP
         mov  EBP,ESP

The BP/EBP value on the stack will be even or odd depending on the code model.  For 16-bit DOS systems, the Dynamic Overlay Manager uses this information to determine if the return address on the stack is a short address (16-bit offset) or long address (32-bit segment:offset).  This option is not assumed by default.

OH

This option enables repeated optimizations (which can result in longer compiles).

OI

This option causes code for statement functions to be generated in-line.

OK

This option enables flowing of register save (from prologue) down into the subprogram's flow graph.

OL

Loop optimizations are performed.  This includes moving loop-invariant expressions outside the loops.  This option is not assumed by default.

OL+

Loop optimizations are performed including loop unrolling.  This includes moving loop-invariant expressions outside the loops and can cause loops to be turned into straight-line code.  This option is not assumed by default.

OM

Generate inline 80x87 code for math functions like sin, cos, tan, etc.  If this option is selected, it is the programmer's responsibility to make sure that arguments to these functions are within the range accepted by the fsin, fcos, etc.   instructions since no run-time check is made.
If the "ot" option is also specified, the exp function is generated inline as well.  This option is not assumed by default.

ON

This option allows the compiler to perform certain numerical calculations in a more efficient manner.  Consider the following example.
     
     Z1 = X1 / Y
     Z2 = X2 / Y

If the "on" option is specified, the code generator will generate code that is equivalent to the following.

     
     T = 1 / Y
     Z1 = X1 * T
     Z2 = X2 * T

Since floating-point multiplication is more efficient that division, the code generator decided to first compute the reciprocal of Y and then multiply X1 and X2 by the reciprocal of Y.
Note that this optimization may produce less slightly different results since some, for certain values, precision is lost when computing the reciprocal.  By using this option, you are indicating that you are willing to accept the loss in precision for the gain in performance.

OP

By default, floating-point variables may be cached in 80x87 floating-point registers across statements when compiling with the "fpi" or "fpi87" options.  Floating-point register temporaries use 64 bits of precision in the mantissa whereas single and double-precision variables use fewer bits of precision in the mantissa.  The use of this option will force the result to be stored in memory after each FORTRAN statement is executed.  This will produce less accurate but more predictable floating-point results.  The code produced will also be less efficient when the "op" option is used.
Example:

     XMAX = X + Y / Z
     YMAX = XMAX + Q

When the "op" option is used in conjunction with the "fpi" or "fpi87" option, the compiler's code generator will update XMAX before proceeding with the second statement.  In the second statement, the compiler will reload XMAX from memory rather than using the result of the previous statement.  The effect of the "op" option on the resulting code can be seen by the increased code size statistic as well as through the use of the Open Watcom Disassembler.  This option is not assumed by default.

OR

This option enables reordering of instructions (instruction scheduling) to achieve better performance on pipelined architectures such as the 486.  Selecting this option will make it slightly more difficult to debug because the assembly language instructions generated for a source statement may be intermixed with instructions generated for surrounding statements.  This option is not assumed by default.

OS

Space is favoured over time when generating code (smaller code but possibly slower execution).  By default, Open Watcom F77 selects a balance between "space" and "time".

OT

Time is favoured over space when generating code (faster execution but possibly larger code).  By default, Open Watcom F77 selects a balance between "space" and "time".

OX

Specifying the "ox" option is equivalent to specifying the "ob" (32-bit only), "obp", "odo", "oi", "ok", "ol", "om", "or", and "ot" options.

PRint

This option is used to direct the listing file to the printer (device name "PRN") instead of the disk.  The "print" option will override any previously specified "type" or "disk" option.  The default is to create a listing file on the disk.

[NO]Quiet

The "quiet" option suppresses the banner and summary information produced by the compiler.  Only diagnostic messages will be displayed.  The default option is "noquiet".

[NO]Reference

When the "reference" option is specified, warning messages will be issued for all unreferenced symbols.  In a source file, the option appears as a comment line and takes the following form.
     
     *$[NO]Reference

This option is most useful when used in an include file that is included by several subprograms.  Consider an include file that defines many parameter constants and only a few are referenced by any one subprogram.  If the first line of the include file is

     
     *$noreference

and the last line is

     
     *$reference

warning messages for all unused parameter constants in the include file would be suppressed.  The default option is "reference".

[NO]RESource

The "resource" option specifies that the run-time error messages are contained as resource information in the executable file.  All messages will be extracted from the resource area of the executable file when they are required; no messages will be linked with the application.  The default option is "noresource".

[NO]SAve

The "save" option is used to instruct Open Watcom F77 to "save" all local variables of subprograms.  All local variables are treated as if they had appeared in FORTRAN 77 SAVE statements.  By default, local variables are not saved unless named in a SAVE statement (i.e., "nosave" is the default option).

[NO]SC

(32-bit only) If the "sc" option is used, Open Watcom F77 will pass all arguments on the stack.  The resulting code will be larger than that which is generated for the register method of passing arguments.  The default option is "nosc".

[NO]SEpcomma

The "sepcomma" option allows the comma (",") to be used as field separator in formatted input.  Thus the following code would work with the input described.
Example:

         REAL R, S

         READ(5,21) R, S
         PRINT *, R, S
     21  FORMAT(2F11.3)
         END

Normally the following input would result in a run-time error message.

     
     0.79,0.21

[NO]SG

(32-bit only) The "sg" option is useful for 32-bit OS/2 multi-threaded applications.  It requests the code generator to emit a run-time call at the start of any function that has more than 4K bytes of automatic variables (variables located on the stack).  Under 32-bit OS/2, the stack is grown automatically in 4K pages using the stack "guard page" mechanism.  The stack consists of in-use committed pages topped off with a special guard page.  A memory reference into the 4K guard page causes OS/2 to grow the stack by one 4K page and to add a new 4K guard page.  This works fine when there is less than 4K of automatic variables in a function.  When there is more than 4K of automatic data, the stack must be grown in an orderly fashion, 4K bytes at a time, until the stack has grown sufficiently to accommodate all the automatic variable storage requirements.
The "stack growth" run-time routine is called __GRO.

The default option is "nosg".

[NO]SHort

The "short" option is used to instruct Open Watcom F77 to set the default INTEGER size to 2 bytes and the default LOGICAL size to 1 bytes.  As required by the FORTRAN 77 language standard, the default INTEGER size is 4 bytes and the default LOGICAL size is 4 bytes.  The default option is "noshort".

[NO]SR

The "sr" option instructs Open Watcom F77 to generate subprogram prologue and epilogue sequences that save and restore any segment registers that are modified by the subprogram.  Caution should be exercised when using this option.  If the value of the segment register being restored matches the value of a segment that was freed within the subprogram, a general protection fault will occur in protected-mode environments.  The default, "nosr", does not save and restore segment registers.

[NO]SSfloats

(16-bit only) The "ssfloats" option specifies that the segment register SS does not necessarily point to the default data segment.  The "ssfloats" option must be specified when compiling a module that is part of an OS/2 multi-threaded application or dynamic link library.  By default, it is assumed that the SS segment register contains the segment address of the default data segment (i.e., "nossfloats").

[NO]STack

If "stack" is specified, Open Watcom F77 will emit code at the beginning of every subprogram that will check for the "stack overflow" condition.  By default, stack overflow checking is omitted from the generated code ("nostack").

[NO]SYntax

If "syntax" is specified, Open Watcom F77 will check the source code only and omit the generation of object code.   Syntax checking, type checking, and so on are performed as usual.  By default, code is generated if there are no source code errors (i.e., "nosyntax" is the default).

[NO]TErminal

The "noterminal" option may be used to suppress the display of diagnostic messages to the screen.  By default, diagnostic messages are displayed.

[NO]TRace

The "trace" option causes the generation of code that allows a traceback to be issued when an error occurs during the execution of your program.  The default option is "notrace".

TYpe

This option is used to direct the listing file to the terminal (device name "CON") instead of the disk.  The "type" option will override any previously specified "print" or "disk" option.  The default is to create a listing file on the disk.

[NO]WArnings

This option is used to control the printing of warning messages.  By default, warning messages are printed.  This option may be specified on the command line or it may be placed anywhere in the source input stream.  In a source file, the option appears as a comment line and takes the following form.
     
     *$[NO]WArnings

The "warnings" option enables the printing of warning messages, while "nowarnings" disables the printing of these messages.

[NO]WILd

The "wild" option suppresses the compile-time checking that normally causes an error to be issued when an attempt is made to transfer control into a block structure from outside the block structure and vice versa.  For example, this option will allow a transfer of control into an IF-block from outside the IF-block (which is normally prohibited).  The default option is "nowild".
Extreme caution should be exercised when using this option.  For example, transfer of control into a DO-loop from outside the DO-loop can cause unpredictable results.  This programming style is not encouraged by this option.  The option has been made available so that existing programs that do not adhere to the branching restrictions imposed by the FORTRAN 77 standard (i.e.  mainframe applications that are being ported to the PC environment), can be compiled by Open Watcom FORTRAN 77.

[NO]WIndows

(16-bit only) The "windows" option causes the compiler to generate the prologue/epilogue code sequences necessary for use in Microsoft Windows applications.  The default option is "nowindows".

[NO]XFloat

The "xfloat" option specifies that all REAL variables are treated as if they had been declared as "DOUBLE PRECISION".   This effectively increases the precision of REAL variables.  Note that the "xfloat" option has implications on the alignment of variables in common blocks.  The default option is "noxfloat".

[NO]Xline

The "xline" option informs the Open Watcom F77 compiler to extend the last column of the statement portion of a line to column 132.  The default is 72.

The Open Watcom FORTRAN 77 Compiler

• Command line syntax (see Open Watcom FORTRAN 77 Command Line Format)
• Environment variables used by the compilers (see WFC/WFC386 Environment Variables)
• Examples of command line syntax (see Open Watcom FORTRAN 77 Command Line Examples)
• Interpreting diagnostic messages (see Compiler Diagnostics)
• Include file handling (see Open Watcom FORTRAN 77 INCLUDE File Processing)

Open Watcom FORTRAN 77 Command Line Format

WFC

is the name of the 16-bit Open Watcom F77 compiler.

WFC386

is the name of the 32-bit Open Watcom F77 compiler.

d:

is an optional drive specification such as "A:", "B:", etc.  If not specified, the default drive is assumed.

path

is an optional path specification such as \PROGRAMS\SRC\.  If not specified, the current directory is assumed.

filename

is the file name of the file to be compiled.

ext

is the file extension of the file to be compiled.  If omitted, a file extension of "FOR" is assumed.  If the period "." is specified but not the extension, the file is assumed to have no file extension.

options

is a list of valid Open Watcom F77 options, each preceded by a slash ("/") or a dash ("-").  Certain options can include a "no" prefix to disable an option.  Options may be specified in any order, with the rightmost option taking precedence over any conflicting options specified to its left.

WFC/WFC386 Environment Variables

Open Watcom FORTRAN 77 Command Line Examples

Compiler Diagnostics

Open Watcom FORTRAN 77 INCLUDE File Processing

The Open Watcom FORTRAN 77 Libraries

M

denotes a version of the 16-bit Open Watcom FORTRAN 77 libraries which have been compiled for the "medium" memory model (big code, small data). 

L

denotes a version of the 16-bit Open Watcom FORTRAN 77 libraries which have been compiled for the "large" or "huge" memory models (big code, big data or huge data). 

7

denotes a version of the Open Watcom FORTRAN 77 libraries which should be used when compiling with the "fpi" or "fpi87" option.  Otherwise the libraries have been compiled using the "fpc" compiler option. 

S

denotes a version of the 32-bit Open Watcom FORTRAN 77 libraries which have been compiled using the "sc" option (stack calling conventions).

Open Watcom FORTRAN 77 80x87 Emulator Libraries

The "NO87" Environment Variable

Open Watcom FORTRAN 77 Compiler Directives

1. EJECT
2. INCLUDE
3. PRAGMA
4. DEFINE
5. UNDEFINE
6. IFDEF
7. IFNDEF
8. ENDIF
9. ELSE
10. ELIFDEF
11. ELIFNDEF

1. [NO]EXTENSIONS
2. [NO]LIST
3. [NO]REFERENCE
4. [NO]WARNINGS

The EJECT Compiler Directive

The INCLUDE Compiler Directive

1. First, the current directory is searched.
2. Secondly, each directory listed with the "INCPath" option is searched (in the order that they were specified).
3. Thirdly, each directory listed in the FINCLUDE environment variable is searched (in the order that they were specified).

The PRAGMA Compiler Directive

The DEFINE Compiler Directive

The UNDEFINE Compiler Directive

The IFDEF, IFNDEF and ENDIF Compiler Directive

The ELSE Compiler Directive

The ELSEIFDEF and ELSEIFNDEF Compiler Directive

Debugging statements ("D" in Column 1)

General Notes About Compiler Directives

1. Compiler directives must not contain embedded blanks.  The following is not a valid ENDIF compiler directive.
   
   Example:
   
        *$end if
2. Nesting is allowed up to a maximum of 16 levels.
   
   Example:
   
        *$ifdef sym1
            <statements>
        *$ifdef sym2
            <statements>
        *$endif
        *$endif
3. The macro __i86__ is a special macro that is defined by the compiler and identifies the target as a 16-bit Intel 80x86 compatible environment.
4. The macro __386__ is a special macro that is defined by the compiler and identifies the target as a 32-bit Intel 80386 compatible environment.
5. The macro __stack_conventions__ is a special macro that is defined by the 32-bit compiler when stack conventions are used for code generation.  Stack conventions are used when the "sc" or "3s" compiler options are specified.
6. The macro __fpi__ is a special macro that is defined by the compiler when one of the following floating-point options is specified:  "fpi" or "fpi87".
7. The macro __debug__ is a special macro that can be used to conditionally compile debugging statements.  A debugging statement is one that contains the character "D" or "d" in column one.

Open Watcom FORTRAN 77 File Handling

1. the techniques that Open Watcom F77 adopts for implementing FORMATTED and UNFORMATTED records and SEQUENTIAL and DIRECT access to these records,
2. the handling of "print" files,
3. file naming conventions,
4. logical file names,
5. the preconnection of files to units, and
6. special device support.

Record Access

Sequential

Sequential access means that records in a file are accessed in order, starting with the first record in the file and proceeding to the last.  Sequential access is permitted to records in both variable-length and fixed-length record files.

Direct

Direct access means that records in a file are accessed in random order.  For example, the fifth record could be accessed, then the second, and then the tenth.  Direct access is permitted for fixed-length record files only.

Record Format

FORMATTED Records

UNFORMATTED Records

Files with no Record Structure

1. You can use unformatted direct access.  In this case, the value specified by the RECL= specifier in the OPEN statement determines the amount of data read or written by a READ or WRITE statement.
2. Alternatively, you can use unformatted sequential access.  In this case, the amount of data read or written to the file is determined by the items in the input/output list of the READ or WRITE statement.  When using unformatted sequential access, you must specify RECORDTYPE='FIXED' to indicate that no record boundaries are present.  Otherwise, the default value of 'VARIABLE' will be used.

Attributes of Files

Record Type

TEXT

indicates that the file contains variable-length or fixed-length records of ASCII characters separated by an ASCII "LF" (line feed) character optionally preceded with an ASCII "CR" (carriage return) character.  By default, the Open Watcom F77 run-time system assumes that FORMATTED records are of TEXT format in both the sequential and direct access modes.
By default, the Open Watcom F77 run-time system uses variable-length record TEXT files to implement FORMATTED records in the sequential access mode.  Of course, all records may be the same length.  The record separator is not included in calculating the maximum size of records in the file.

By default, the Open Watcom F77 run-time system uses fixed-length record TEXT files to implement FORMATTED records in the direct access mode.  Each record must be the same length.  The record separator is not included in calculating the size of records in the file.

VARIABLE

indicates that the file contains variable-length or fixed-length records in which special descriptors are employed to describe the length of each record.  The length of each record is contained in a doubleword (INTEGER*4 item) at the beginning and end of the record.  These descriptors determine the bounds of the records.
By default, the Open Watcom F77 run-time system uses VARIABLE format files to implement UNFORMATTED records in the sequential access mode.  The length descriptors are required to support the FORTRAN BACKSPACE statement since no other method exists for determining the bounds of a variable-length unformatted record in a file.

FIXED

indicates that the file contains no extra information that determines the record structure.  If the file is a direct access file, the value specified by the RECL= specifier determines the size of each record in the file.
By default, the Open Watcom F77 run-time system uses FIXED format files to implement UNFORMATTED records in the direct access mode.

If you specify FIXED with an unformatted sequential file, the size of the records is determined by the items in the input/output list.

Record Size

Print File Attributes

"1"

Advance to Top of Page

"+"

Advance Zero Lines (overprint)

" "

Advance 1 Line

"0"

Advance 2 Lines

"-"

Advance 3 Lines

"1"

Substitute a FF (form feed) for the "1".

"+"

Append only a CR (carriage return ) to the previous record.

" "

Throw away the blank character.

"0"

Substitute CR (carriage return) and LF (line feed) for the "0".

"-"

Substitute two pairs of CR and LF for the "-".
Any other character in this position will be treated as if a blank character had been found (i.e., it will be discarded).

Input/Output Buffer Size

File Sharing

'READ'

the file is opened for read-only access

'WRITE'

the file is opened for write-only access

'READWRITE'

the file is opened for both read and write access

'COMPAT'

no other process may open the file

'DENYRW'

other processes are denied read and write access

'DENYWR'

other process are denied write access (allowed read-only access)

'DENYRD'

other process are denied read access (allowed write-only access)

'DENYNONE'

other processes are allowed read and write access

File Names in the FAT File System

[]

The square brackets denote items which are optional. 

d:

is the drive name.  If omitted, the default drive is assumed.
Examples of drive names are:  a:, b:, c:, and d:. 

path

is called a "path" specification.  The path may be used to refer to files that are stored in sub-directories of the disk.  The complete file specification (including drive, path and file name) cannot exceed 143 characters.
Some examples of path specifications are:

     
     \plot\
     \bench\tools\
     \fortran\pgms\

Your operating system manuals can tell you more about directories:  how to create them, how to store files in them, how to specify a path, etc. 

filename

is the main part of the file's name.  The filename can contain up to 8 characters.  If more than 8 characters are used, only the first 8 are meaningful.  For example, "COUNTRIES" and "COUNTRIE" are treated as the same name for a file. 

ext

is an optional extension consisting of 1 to 3 characters (e.g., DOC).  If an extension is specified, it is separated from the filename by a period.  Extensions are normally used to indicate the type of information stored in the file.   For example, a file extension of for is a common convention for FORTRAN programs.

Special DOS Device Names

Examples of FAT File Specifications

1. The following file designation refers to a file in the current directory of the default disk.
   
        
        OPEN( UNIT=1, FILE='DATA.FIL', ... )
2. The following file designation refers to a print file in the current directory of drive c:.  ASA carriage control characters will be converted to the appropriate ASCII control codes.
   
        
        OPEN( UNIT=2, FILE='c:report.lst',
              CARRIAGECONTROL='YES', ... )
3. The file specification below indicates that the file is to have fixed format records of length 80.
   
        
        OPEN( UNIT=3, FILE='final.tst',
              RECL=80, RECORDTYPE='FIXED', ... )
4. The file specification below indicates that the file is to have variable format records of maximum length 145.
   
        
        OPEN( UNIT=4, FILE='term.rpt',
              RECL=145, RECORDTYPE='VARIABLE', ... )
5. The file designation below indicates that the file resides in the records directory of drive b:.
   
        
        OPEN( UNIT=5, FILE='b:\records\customers.dat', ... )
   
   Note that the trailing "S" in the file name will be ignored.  Thus the following designation is equivalent.
   
        
        OPEN( UNIT=5, FILE='b:\records\customer.dat', ... )
6. The file designation below refers to the second serial port.
   
        
        OPEN( UNIT=6, FILE='com2', ... )
7. The file designation below refers to a second parallel printer.
   
        
        OPEN( UNIT=7, FILE='lpt2', ... )

File Names in the High Performance File System

Special OS/2 Device Names

Examples of HPFS File Specifications

1. The following file designation refers to a file in the current directory of the default disk.
   
        
        OPEN( UNIT=1, FILE='DATA.FIL', ... )
2. The following file designation refers to a print file in the current directory of drive c:.  ASA carriage control characters will be converted to the appropriate ASCII control codes.
   
        
        OPEN( UNIT=2, FILE='c:report.lst',
              CARRIAGECONTROL='YES', ... )
3. The file specification below indicates that the file is to have fixed format records of length 80.
   
        
        OPEN( UNIT=3, FILE='final.tst',
              RECL=80, RECORDTYPE='FIXED', ... )
4. The file specification below indicates that the file is to have variable format records of maximum length 145.
   
        
        OPEN( UNIT=4, FILE='term.rpt',
              RECL=145, RECORDTYPE='VARIABLE', ... )
5. The file designation below indicates that the file resides in the records directory of drive b:.
   
        
        OPEN( UNIT=5, FILE='b:\records\customers.dat', ... )
   
   Note that the trailing "S" in the file name is not ignored as is the case in a FAT file system.
6. The file designation below refers to the second serial port.
   
        
        OPEN( UNIT=6, FILE='com2', ... )
7. The file designation below refers to a second parallel printer.
   
        
        OPEN( UNIT=7, FILE='lpt2', ... )

Establishing Connections Between Units and Files

where

description

unit

is a FORTRAN unit number in the range 0 to 999.
If this form of the "SET" command is used then FORTRAN unit number unit is preconnected to the specified file.  FORTRAN input/output statements which refer to the unit number will access the records in the specified file.

file_spec

is the file specification of the preconnected file.

1. Between unit 1 and the file input.dat which resides (or will reside) in the current directory.
2. Between unit 2 and the file output.dat which resides (or will reside) in the current directory.
3. Between unit 3 and the file d:\database\customer.fil which resides (or will reside) in another disk and directory.

1. The "SET" command must be issued before running the program.
2. No spaces should be placed before or after the "=" in the "SET" command.  The following two examples are quite distinct from each other:
   
   Example:
   
        C>set 55=testbed.dat
        C>set 55 = testbed.dat
   
   To verify this, simply enter the two commands and then enter the "SET" command again with no arguments.   The current environment strings will be displayed.  You should find two entries, one for "55" and one for "55 ".
3. Since the number in front of the "=" is simply a character string, you should not specify any leading zeroes either.
   
   Example:
   
        C>set 01=input.dat
        C>set 1=input.dat
   
   In this case, we again have two distinct environment variables.  The variable "01" will be ignored by the Open Watcom F77 run-time system.
4. An environment variable will remain in effect until you explicitly remove it or you turn off the personal computer.  To discontinue the preconnection between a unit number and a file, you must issue a "SET" command of the following form.
   
        
        C>set <unit>=
   
   In the above command, <unit> is the unit number for which the preconnection is to be discontinued.
   
   By omitting the character string after the "=", the environment variable will be removed.  For example, to remove the environment variable "01" from the list, reenter the "SET" command specifying everything up to and including the "=" character.
   
   Example:
   
        C>set 01=
5. Any time you wish to see the current list of environment strings, simply enter the "SET" command with no arguments.
   
   Example:
   
        C>set
        PROMPT=$d $t $p$_$n$g
        COMSPEC=d:\dos\command.com
        PATH=G:\;E:\CMDS;C:\WATCOM\BIN;D:\DOS;D:\BIN
        LIB=c:\watcom\lib286\dos
        1=input.dat
        2=output.dat
        3=d:\database\customer.fil
6. An alternative to preconnecting files is provided by the FORTRAN OPEN statement which allows files to be connected at execution time.
7. The preconnection of units 5 and 6 may be overridden using preconnection specifications or the FORTRAN OPEN statement.  The precedence of a connection between a unit number and a file is as follows:

   Precedence:

   User option:

   
   Lowest

   Preconnection Specifications

   
   Highest

   OPEN statement

   
   In other words, the OPEN statement overrides a preconnection.

A Preconnection Tutorial

Logical File Name Support

where

description

name

is any character string.  The letters in "name" may be specified in upper or lower case.  Lower case letters are treated as if they had been specified in upper case.  Thus "SYSINPUT" and "sysinput" are equivalent.   Note, however, that blank characters must not be specified before and after the "=" character.

file_spec

is the file specification of logical file.

1. A logical file name may be used in the FILE= specifier of the FORTRAN OPEN and INQUIRE statements.
   
   Example:
   
        * File 'iodemo.for'
              OPEN( 1, FILE='SYSINPUT' )
        10    READ( 1, *, END=99 ) X1, X2
              WRITE( 6, 20 ) X1, X2, X1 + X2
              GO TO 10
        20    FORMAT( 3F6.2 )
        99    END
   
   In the following example, we define the logical file name "SYSINPUT" to correspond to the file numbers.dat.
   
   Example:
   
        C>set sysinput=numbers.dat
        C>iodemo
          1.40  2.50  3.90
          3.90  8.70 12.60
          1.10  9.90 11.00
          8.30  7.10 15.40
          8.20  3.50 11.70
2. If the name in a FILE= specifier is not included in one of the environment variable names then it is assumed to be the actual name of a file.
   
   Example:
   
        OPEN( 2, FILE='SYSOUT' )
3. The logical file name feature can also be used to provide additional information regarding the file name at execution time.
   
   Example:
   
        * File 'iodemo.for'
              OPEN( 1, FILE='numbers.dat' )
        10    READ( 1, *, END=99 ) X1, X2
              WRITE( 6, 20 ) X1, X2, X1 + X2
              GO TO 10
        20    FORMAT( 3F6.2 )
        99    END
   
   In the following example, the actual location (and name) of the file numbers.dat is described through the use of an environment variable.
   
   Example:
   
        C>set numbers.dat=b:\data\input.dat
        C>iodemo
   
   As you can see, a logical file name can resemble an actual file name.
   
   Of course, the entire file name could have been specified in the FORTRAN program.
   
   Example:
   
        OPEN( 1, FILE='b:\data\input.dat' )
4. Only one level of lookup is performed.
   
   Example:
   
        * File 'iodemo.for'
              OPEN( 1, FILE='sysinput' )
        10    READ( 1, *, END=99 ) X1, X2
              WRITE( 6, 20 ) X1, X2, X1 + X2
              GO TO 10
        20    FORMAT( 3F6.2 )
        99    END
   
   This is illustrated by the following commands.
   
   Example:
   
        C>set sysinput=datafile
        C>set datafile=input.dat
        C>iodemo
   
   In the above example, unit 1 is connected to the file datafile and not the file input.dat. 
5. Logical file names can be used to direct output normally intended for one device to another device.  Consider the following examples.
   
   Example:
   
        C>set lpt1=lpt2
   
   If the FORTRAN program specifies the name "LPT1" in an OPEN or INQUIRE statement, the Open Watcom F77 run-time system will map this name to "LPT2".  In an INQUIRE statement, the NAME= specifier will return the name "LPT2".
6. As we mentioned earlier, the case of the name does not matter.  Upper or lower case can be used interchangeably.
   
   Example:
   
        C>set sysinput=b:\data\input.dat
        C>set SYSINPUT=b:\data\input.dat
7. No spaces should be placed before or after the "=" in the "SET" command.  The following two examples are considered quite distinct from each other:
   
   Example:
   
        C>set sysinput=testbed.dat
        C>set sysinput = testbed.dat
   
   This example will define two variables, "SYSINPUT" and "SYSINPUT ".
8. An environment variable will remain in effect until you explicitly remove it or you turn off the personal computer.  To remove an environment variable from the list, reenter the "SET" command specifying everything up to and including the "=" character.  For example, to remove the definition for "SYSINPUT", the following command can be issued.
   
   Example:
   
        C>set sysinput=
9. Any time you wish to see the current list of environment strings, simply enter the "SET" command with no arguments.
   
   Example:
   
        C>set
        PROMPT=$d $t $p$_$n$g
        COMSPEC=d:\dos\command.com
        PATH=G:\;E:\CMDS;C:\WATCOM\BIN;D:\DOS;D:\BIN
        LIB=c:\watcom\lib286\dos
        1=input.dat
        2=output.dat
        3=d:\database\customer.fil
        SYSINPUT=b:\data\input.dat
        LPT1=lpt2

Terminal or Console Device Support

'READ'

the file is opened for read-only access

'WRITE'

the file is opened for write-only access

'READWRITE'

the file is opened for both read and write access

Printer Device Support

Serial Device Support

File Handling Defaults

• The following table indicates the default record type for the allowable access methods and forms.
  
       
       File                     Form
       Access         Formatted   Unformatted
                     +-----------+-----------+
       Sequential    |   Text    | Variable  |
                     +-----------+-----------+
       Direct        |   Text    | Fixed      |
                     +-----------+-----------+
  
  Unless the record type of the file does not correspond to the default assumed by Open Watcom F77, the record type attribute should not be specified.
• Unless otherwise stated, the default record length for a file is 1024 characters.  When access is "direct", the record length must be specified in the RECL= specifier of the FORTRAN OPEN statement.  The record length may also be specified when the access is "sequential".  This should be done whenever access is "sequential" and the maximum record length is greater than the default.
• The default record access is "sequential".
• When reading from or writing to a unit for which no preconnection has been specified or no "FILE=" form of the FORTRAN OPEN statement has been executed, the default file name takes the form:
  
       
       FORnnn
  
  nnn is a three-digit FORTRAN unit number.  Unit 0 is "000", unit 1 is "001", unit 2 is "002", and so on.  There is no file extension in this case.
• If the connection between a unit number and a file is discontinued through use of the FORTRAN CLOSE statement, the same rule for constructing a file name will apply on the next attempt to read from or write to the specified unit.

The Open Watcom F77 Subprogram Library

Subroutine FEXIT

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

INTEGER Function FGETCMD

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. If the argument to FGETCMD is not long enough then only the first part of the command line is returned.

INTEGER Function FGETENV

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. If the second argument to FGETENV is not long enough then only the first part of the value is returned.

INTEGER Function FILESIZE

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

Subroutine FINTR and FINTRF

1. The first argument is an interrupt number.  These subroutines will generate the software interrupt given by the this argument.  The type must be INTEGER.
2. The second argument is an INTEGER array of ten elements.

INTEGER Function FLUSHUNIT

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

INTEGER Function FNEXTRECL

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

INTEGER Function FSIGNAL

Event

Meaning

SIGBREAK

an interactive attention (Ctrl/Break on keyboard) is signalled

SIGFPE

an erroneous floating-point operation occurs (such as division by zero, overflow and underflow)

SIGILL

illegal instruction encountered

SIGINT

an interactive attention (Ctrl/C on keyboard) is signalled

SIGSEGV

an illegal memory reference is detected

SIGTERM

a termination request is sent to the program

SIGIDIVZ

integer division by zero

SIGIOVFL

integer overflow

1. a subprogram that is called when the event occurs
2. the value SIG_DFL, causing the default action to be taken when the event occurs
3. the value SIG_IGN, causing the event to be ignored

1. The FORTRAN include file fsignal.fi contains typing and calling information for FSIGNAL and should be included when using this function.  This file is located in the \watcom\src\fortran directory.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. The intrinsic function VOLATILE is used to indicate that the reference to the variable break_flag is volatile.  A volatile reference prevents the compiler from caching a variable in a register.  In this case, we want to retrieve the value of break_flag from memory each time the loop is iterated.

INTEGER Function FSPAWN

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. The INTEGER function FSYSTEM, which is described in a later section, implements a more general form of the example given above.  We recommend its use.

INTEGER Function FSYSTEM

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

Subroutine FTRACEBACK

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

Subroutine GETDAT

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. The arguments to GETDAT must be of type INTEGER*2 in order to obtain correct results.

Subroutine GETTIM

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. The arguments to GETTIM must be of type INTEGER*2 in order to obtain correct results.

INTEGER Function GROWHANDLES

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

Functions IARGC and IGETARG

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.

Math Error Functions

1. The function __imath2err is called for math functions of type INTEGER that take two arguments of type INTEGER.   The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the first argument passed to the math function and the third argument is a pointer to the second argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
2. The function __amath1err is called for math functions of type REAL that take one argument of type REAL.  The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
3. The function __amath2err is called for math functions of type REAL that take two arguments of type REAL.  The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the first argument passed to the math function and the third argument is a pointer to the second argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
4. The function __math1err is called for math functions of type DOUBLE PRECISION that take one argument of type DOUBLE PRECISION.  The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
5. The function __math2err is called for math functions of type DOUBLE PRECISION that take two arguments of type DOUBLE PRECISION.  The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the first argument passed to the math function and the third argument is a pointer to the second argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
6. The function __zmath2err is called for math functions of type COMPLEX that take two arguments of type COMPLEX.   The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the first argument passed to the math function and the third argument is a pointer to the second argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.
7. The function __qmath2err is called for math functions of type DOUBLE COMPLEX that take two arguments of type DOUBLE COMPLEX.  The first argument represents the error information and is an argument of type INTEGER that is passed by value.  The second argument is a pointer to the first argument passed to the math function and the third argument is a pointer to the second argument passed to the math function.  The error function returns a value that is then used as the return value for the math function.

INTEGER Function SEEKUNIT

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. A value of -1 is returned if the requested positioning cannot be done.

INTEGER Function SETJMP/Subroutine LONGJMP

1. The FORTRAN include file setjmp.fi contains typing and calling information for SETJMP and LONGJMP and must be included.  Similarly, fsignal.fi must be included when using the FSIGNAL function.  These files are located in the \watcom\src\fortran directory.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate these include files.

INTEGER Function SETSYSHANDLE

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. A value of -1 is returned if the unit is not connected to a file.
3. Units 5 and 6 are preconnected to the standard input and standard output devices respectively.

INTEGER*2 Function SYSHANDLE

1. The FORTRAN include file fsublib.fi, located in the \watcom\src\fortran directory, contains typing and calling information for this subprogram.  The \watcom\src\fortran directory should be included in the FINCLUDE environment variable so that the compiler can locate the include file.
2. A value of -1 is returned if the unit is not connected to a file.
3. Units 5 and 6 are preconnected to the standard input and standard output devices respectively.

REAL Function URAND

1. Upon each invocation of URAND, the seed argument is updated by the random number generator.  Therefore, the argument must not be a constant and, once the seed value has been set, it must not be modified by the programmer.

Default Windowing Functions

16-bit Windows

C>wfl [fn1] [fn2] ...  -bw -windows -l=windows

32-bit Windows

C>wfl386 [fn1] [fn2] ...  -bw -l=win386
C>wbind -n [fn1]

32-bit Windows NT or Windows 95

C>wfl386 [fn1] [fn2] ...  -bw -l=nt_win

32-bit OS/2 Presentation Manager

C>wfl386 [fn1] [fn2] ...  -bw -l=os2v2_pm

Note:

At present, a restriction in Windows NT prevents you from opening the console device (CON) for both read and write access.   Therefore, it is not possible to open additional windows for both input and output under Windows NT.  They must be either read-only or write-only windows.

dwfDeleteOnClose

dwfSetAboutDlg

dwfSetAppTitle

dwfSetConTitle

dwfShutDown

dwfYield

Data Representation On x86-based Platforms

LOGICAL*1 Data Type

LOGICAL and LOGICAL*4 Data Types

INTEGER*1 Data Type

INTEGER*2 Data Type

INTEGER and INTEGER*4 Data Types

REAL and REAL*4 Data Types

S

S = Sign bit (0=positive, 1=negative)

Exponent

The exponent bias is 127 (i.e., exponent value 1 represents 2**-126; exponent value 127 represents 2**0; exponent value 254 represents 2**127; etc.).  The exponent field is 8 bits long.

Significand

The leading bit of the significand is always 1, hence it is not stored in the significand field.  Thus the significand is always "normalized".  The significand field is 23 bits long.

Zero

A real zero quantity occurs when the sign bit, exponent, and significand are all zero.

Infinity

When the exponent field is all 1 bits and the significand field is all zero bits then the quantity represents positive or negative infinity, depending on the sign bit.

Not Numbers

When the exponent field is all 1 bits and the significand field is non-zero then the quantity is a special value called a NAN (Not-A-Number).
When the exponent field is all 0 bits and the significand field is non-zero then the quantity is a special value called a "denormal" or nonnormal number.

DOUBLE PRECISION and REAL*8 Data Types

S

S = Sign bit (0=positive, 1=negative)

Exponent

The exponent bias is 1023 (i.e., exponent value 1 represents 2**-1022; exponent value 1023 represents 2**0; exponent value 2046 represents 2**1023; etc.).  The exponent field is 11 bits long.

Significand

The leading bit of the significand is always 1, hence it is not stored in the significand field.  Thus the significand is always "normalized".  The significand field is 52 bits long.

Zero

A double precision zero quantity occurs when the sign bit, exponent, and significand are all zero.

Infinity

When the exponent field is all 1 bits and the significand field is all zero bits then the quantity represents positive or negative infinity, depending on the sign bit.

Not Numbers

When the exponent field is all 1 bits and the significand field is non-zero then the quantity is a special value called a NAN (Not-A-Number).
When the exponent field is all 0 bits and the significand field is non-zero then the quantity is a special value called a "denormal" or nonnormal number.

COMPLEX, COMPLEX*8, and DOUBLE COMPLEX Data Types

COMPLEX*16 Data Type

CHARACTER Data Type

Storage Organization of Data Types

Floating-point Accuracy On x86-based Platforms

Floating-point Exceptions On x86-based Platforms

DENORMAL

The result has become denormalized.  When the exponent field is all 0 bits and the significand field is non-zero then the quantity is a special value called a "denormal" or nonnormal number.  By providing a significand with leading zeros, the range of possible negative exponents can be extended by the number of bits in the significand.  Each leading zero is a bit of lost accuracy, so the extended exponent range is obtained by reducing significance.

ZERODIVIDE

A division by zero was attempted.  A real zero quantity occurs when the sign bit, exponent, and significand are all zero.

OVERFLOW

The result has overflowed.  The correct answer is finite, but has a magnitude too great to be represented in the destination floating-point format.

UNDERFLOW

The result has numerically underflowed.  The correct answer is non-zero but has a magnitude too small to be represented as a normal number in the destination floating-point format.  IEEE Standard 754 specifies that an attempt be made to represent the number as a denormal.  This denormalization may result in a loss of significant bits from the significand.

PRECISION

A calculation does not return an exact answer.  This exception is usually masked (disabled) and ignored.  It is used in extremely critical applications, when the user must know if the results are exact.  The precision exception is called "inexact" in IEEE Standard 754.

INVALID

This is the exception condition that covers all cases not covered by the other exceptions.  Included are FPU stack overflow and underflow, NAN inputs, illegal infinite inputs, out-of-range inputs, and inputs in unsupported formats.

Compiler Options Relating to Floating-point

Floating-point Exception Handling

16-bit:  Memory Models

16-bit:  Code Models

1. the small code model
2. the big code model

16-bit:  Data Models

1. the small data model
2. the big data model
3. the huge data model

1. The huge data model has the same characteristics as the big data model, but formal array arguments are assumed to exceed 64kB.  You should use the huge data model whenever any arrays in your application exceed 64kB in size.
2. The huge data model should be used only if needed.  The code generated in the huge data model is not very efficient since a run-time routine is called in order to increment far pointers.  This increases the size of the code significantly and increases execution time.
3. If your program contains less than 64kB of data, you should use the small data model.  This will result in smaller and faster code since references using near pointers produce fewer instructions.

16-bit:  Summary of Memory Models

16-bit:  Mixed Memory Model

16-bit:  Linking Applications for the Various Memory Models

1. The "Library" column specified the library name.
2. The "Memory model" column indicates the compiler options that specify the memory model of the library.
3. The "Floating-point column" indicates the compiler options that specify the floating-point model of the library.

16-bit:  Memory Layout

1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"

1. The "CODE" class contains the executable code for your application.  In a small code model, this consists of the segment "_TEXT".  In a big code model, this consists of the segments "<subprogram>_TEXT" where <subprogram> is the name of a subprogram.
2. The "FAR_DATA" class consists of the following:

   (a)

   arrays whose size exceeds the data threshold in large data memory models (the data threshold is 256 bytes unless changed using the "dt" compiler option)

   
   (b)

   equivalenced variables in large data memory models

16-bit:  Assembly Language Considerations

1. The memory layout of a program compiled by Open Watcom F77.
2. The method for passing arguments and returning values.
3. The two methods for passing floating-point arguments and returning floating-point values.
   
   One method is used when one of the Open Watcom F77 "fpi", "fpi87" or "fpi387" options is specified for the generation of in-line 80x87 instructions.  When the "fpi" option is specified, an 80x87 emulator is included from a math library if the application includes floating-point operations.  When the "fpi87" or "fpi387" option is used exclusively, the 80x87 emulator will not be included.
   
   The other method is used when the Open Watcom F77 "fpc" option is specified.  In this case, the compiler generates calls to floating-point support routines in the alternate math libraries.

16-bit:  Calling Conventions

1. For memory models with a big data model, address of arguments consist of a 16-bit offset and a 16-bit segment.  Hence, two registers are required to pass the address of an argument.  The first argument will be passed in registers DX:AX with register DX containing the segment and register AX containing the offset.  The second argument will be passed in registers CX:BX with register CX containing the segment and register BX containing the offset.
2. For memory models with a small data model, address of arguments consists of only a 16-bit offset into the default data segment.  Hence, only a single register is required to pass the address of an argument.  The first argument is passed in register AX, the second argument is passed in register DX, the third argument is passed in register BX, and the fourth argument is passed in register CX.
3. For any remaining arguments, their address is passed on the stack.  Note that addresses of arguments are pushed on the stack from right to left.

16-bit:  Processing Function Return Values with no 80x87

1. LOGICAL*1 values are returned in register AL.
2. LOGICAL*4 values are returned in registers DX:AX.
3. INTEGER*1 values are returned in register AL.
4. INTEGER*2 values are returned in register AX.
5. INTEGER*4 values are returned in registers DX:AX.
6. REAL*4 values are returned in registers DX:AX.
7. REAL*8 values are returned in registers AX:BX:CX:DX.
8. For COMPLEX*8 functions, space is allocated on the stack by the caller for the return value.  Register SI is set to point to the destination of the result.  The called function places the result at the location pointed to by register SI.
9. For COMPLEX*16 functions, space is allocated on the stack by the caller for the return value.  Register SI is set to point to the destination of the result.  The called function places the result at the location pointed to by register SI.
10. For CHARACTER functions, an additional argument is passed.  This argument is the address of the string descriptor for the result.  Note that the address of the string descriptor can be passed in any of the registers that are used to pass actual arguments.
11. For functions that return a user-defined structure, space is allocated on the stack by the caller for the return value.   Register SI is set to point to the destination of the result.  The called function places the result at the location pointed to by register SI.  Note that a structure of size 1, 2 or 4 bytes is returned in register AL, AX or DX:AX respectively.

16-bit:  Processing Function Return Values Using an 80x87

1. For REAL*4 functions, the result is returned in floating-point register ST(0).
2. For REAL*8 functions, the result is returned in floating-point register ST(0).
3. All other function values are returned in the way described in the previous section.

16-bit:  Processing Alternate Returns

16-bit:  Alternate Method of Passing Character Arguments

1. The first argument would be the address of A.
2. The second argument would be the address of the string descriptor for B.
3. The third argument would be the address of C.
4. The fourth argument would be the address of the string descriptor for D.

1. The first argument would be the address of A.
2. The second argument would be the address of the character data for B.
3. The third argument would be the address of C.
4. The fourth argument would be the address of the character data for D.
5. A hidden argument for the length of B would be the fifth argument.
6. A hidden argument for the length of D would be the sixth argument.

16-bit:  Character Functions

16-bit:  Writing Assembly Language Subprograms

1. All used registers must be saved on entry and restored on exit except those used to pass arguments and return values.   Note that segment registers only have to be saved and restored if you are compiling your application with the "sr" option.
2. The direction flag must be clear before returning to the caller.
3. In a small code model, any segment containing executable code must belong to the segment "_TEXT" and the class "CODE".  The segment "_TEXT" must have a "combine" type of "PUBLIC".  On entry, register CS contains the segment address of the segment "_TEXT".  In a big code model there is no restriction on the naming of segments which contain executable code.
4. In a small data model, segment register DS contains the segment address of the default data segment (group "DGROUP").   In a big data model, segment register SS (not DS) contains the segment address of the default data segment (group "DGROUP").
5. When writing assembly language subprograms for the small code model, you must declare them as "near".  If you wish to write assembly language subprograms for the big code model, you must declare them as "far".
6. Use the ".8087" pseudo-op so that floating-point constants are in the correct format.
7. The called subprogram must remove arguments that were passed on the stack in the "ret" instruction.
8. In general, when naming segments for your code or data, you should follow the conventions described in the section entitled "Memory Layout" in this chapter.

1. The address of the first argument will be passed in registers DX:AX.
2. The address of the second argument will be passed in registers CX:BX.
3. The address of the third argument will be passed on the stack.
4. The address of the fourth argument will be passed on the stack.

1. Two arguments were passed on the stack so a "ret 8" instruction is used to return to the caller.
2. Registers AX, BX, CX and DX were not saved and restored since they were used to pass arguments.  However, registers DS, ES, DI and BP were modified in the subprogram and hence must be saved and restored.

1. The top element of the stack is a segment/offset pair forming a 32-bit return address.  Hence, the third argument will be at offset 4 from the top of the stack and the fourth argument at offset 8.

16-bit:  Returning Values from Assembly Language Functions

1. A LOGICAL*1 function.
   
        
        L1_TEXT segment byte public 'CODE'
                assume  CS:L1_TEXT
                public  L1
        L1      proc    far
   
                mov     AL,1
                ret
        L1      endp
        L1_TEXT ends
                end
2. A LOGICAL*4 function.
   
        
        L4_TEXT segment byte public 'CODE'
                assume  CS:L4_TEXT
                public  L4
        L4      proc    far
                mov     AX,0
   
                cwd
                ret
        L4      endp
        L4_TEXT ends
                end
3. An INTEGER*1 function.
   
        
        I1_TEXT segment byte public 'CODE'
                assume  CS:I1_TEXT
                public  I1
        I1      proc    far
   
                mov     AL,73
                ret
        I1      endp
        I1_TEXT ends
                end
4. An INTEGER*2 function.
   
        
        I2_TEXT segment byte public 'CODE'
                assume  CS:I2_TEXT
                public  I2
        I2      proc    far
                mov     AX,7143
   
                ret
        I2      endp
        I2_TEXT ends
                end
5. An INTEGER*4 function.
   
        
        I4_TEXT segment byte public 'CODE'
                assume  CS:I4_TEXT
                public  I4
        I4      proc    far
                mov     AX,383
   
                cwd
                ret
        I4      endp
        I4_TEXT ends
                end
6. A REAL*4 function.
   
        
        .8087
   
        DGROUP  group R4_DATA
   
        R4_TEXT segment byte public 'CODE'
                assume  CS:R4_TEXT
                assume  SS:DGROUP
                public  R4
        R4      proc    far
   
                mov     AX,word ptr SS:R4Val
                mov     DX,word ptr SS:R4Val+2
                ret
        R4      endp
        R4_TEXT ends
   
        R4_DATA segment byte public 'DATA'
        R4Val   dd 1314.3
        R4_DATA ends
   
                end
7. A REAL*8 function.
   
        
        .8087
   
        DGROUP  group R8_DATA
   
        R8_TEXT segment byte public 'CODE'
                assume  CS:R8_TEXT
                assume  SS:DGROUP
                public  R8
        R8      proc    far
                mov     DX,word ptr SS:R8Val
   
                mov     CX,word ptr SS:R8Val+2
                mov     BX,word ptr SS:R8Val+4
                mov     AX,word ptr SS:R8Val+6
                ret
        R8      endp
        R8_TEXT ends
   
        R8_DATA segment byte public 'DATA'
        R8Val   dq 103.3
        R8_DATA ends
   
                end
8. A COMPLEX*8 function.
   
        
        .8087
   
        DGROUP  group C8_DATA
   
        C8_TEXT segment byte public 'CODE'
                assume  CS:C8_TEXT
                assume  SS:DGROUP
   
                public  C8
        C8      proc    far
                push    DI
                push    ES
                xchg    DI,SI
                push    SS
   
                pop     ES
                mov     SI,offset SS:C8Val
                movsw
                movsw
   
                movsw
                movsw
                pop     ES
                pop     DI
                ret
   
        C8      endp
        C8_TEXT ends
   
        C8_DATA segment byte public 'DATA'
        C8Val   dd 2.2
                dd 2.2
        C8_DATA ends
   
                end
9. A COMPLEX*16 function.
   
        
        .8087
   
        DGROUP  group C16_DATA
   
        C16_TEXT segment byte public 'CODE'
                assume  CS:C16_TEXT
                assume  SS:DGROUP
   
                public  C16
        C16     proc    far
                push    DI
                push    ES
                push    CX
   
                xchg    DI,SI
                push    SS
                pop     ES
                mov     SI,offset SS:C16Val
                mov     CX,8
   
                repe    movsw
                pop     CX
                pop     ES
                pop     DI
                ret
        C16     endp
        C16_TEXT ends
   
        C16_DATA segment byte public 'DATA'
        C16Val  dq 3.3
                dq 3.3
        C16_DATA ends
   
                end
10. A CHARACTER function.
    
         
         CHR_TEXT segment byte public 'CODE'
                 assume  CS:CHR_TEXT
                 public  CHR
         CHR     proc    far
                 push    DI
    
                 push    ES
                 mov     ES,DX
                 mov     DI,AX
                 les     DI,ES:[DI]
    
                 mov     byte ptr ES:[DI],'F'
                 pop     ES
                 pop     DI
                 ret
    
         CHR     endp
         CHR_TEXT ends
    
                 end
11. A function returning a user-defined structure.
    
         
         DGROUP  group STRUCT_DATA
    
         STRUCT_TEXT segment byte public 'CODE'
                 assume  CS:STRUCT_TEXT
                 assume  SS:DGROUP
    
                 public  C16
         STRUCT  proc    far
                 push    DI
                 push    ES
    
                 push    CX
                 xchg    DI,SI
                 push    SS
                 pop     ES
                 mov     SI,offset SS:StructVal
    
                 mov     CX,4
                 repe    movsw
                 pop     CX
                 pop     ES
                 pop     DI
                 ret
    
         STRUCT  endp
         STRUCT_TEXT ends
    
         STRUCT_DATA segment byte public 'DATA'
         StructVal dd 7
                   dd 3
         STRUCT_DATA ends
    
                 end

1. A REAL*4 function using an 80x87.
   
        
        .8087
   
        DGROUP  group R4_DATA
   
        R4_TEXT segment byte public 'CODE'
                assume  CS:R4_TEXT
                assume  SS:DGROUP
   
                public  R4
        R4      proc    far
                fld     dword ptr SS:R4Val
                ret
        R4      endp
        R4_TEXT ends
   
        R4_DATA segment byte public 'DATA'
        R4Val   dd 1314.3
        R4_DATA ends
   
                end
2. A REAL*8 function using an 80x87.
   
        
        .8087
   
        DGROUP  group R8_DATA
   
        R8_TEXT segment byte public 'CODE'
                assume  CS:R8_TEXT
                assume  SS:DGROUP
   
                public  R8
        R8      proc    far
                fld     qword ptr SS:R8Val
                ret
        R8      endp
        R8_TEXT ends
   
        R8_DATA segment byte public 'DATA'
        R8Val   dq 103.3
        R8_DATA ends
   
                end

1. The ".8087" pseudo-op must be specified so that all floating-point constants are generated in 8087 format.
2. When returning values on the stack, remember to use a segment override to the stack segment (SS).

16-bit:  Pragmas

• Pragmas can be used to direct the Open Watcom F77 code generator to emit specialized sequences of code for calling functions which use argument passing and value return techniques that differ from the default used by Open Watcom F77.
• Pragmas can be used to describe attributes of functions (such as side effects) that are not possible at the FORTRAN 77 language level.  The code generator can use this information to generate more efficient code.
• Any sequence of in-line machine language instructions, including DOS and BIOS function calls, can be generated in the object code.

keywords

A keyword is shown in a mono-spaced courier font.

program-item

A program-item is shown in a roman bold-italics font.  A program-item is a symbol name or numeric value supplied by the programmer.

punctuation

A punctuation character shown in a mono-spaced courier font must be entered as is.
A punctuation character shown in a roman bold-italics font is used to describe syntax.  The following syntactical notation is used.

[abc]

The item abc is optional.

{abc}

The item abc may be repeated zero or more times.

a|b|c

One of a, b or c may be specified.

a ::= b

The item a is defined in terms of b.

(a)

Item a is evaluated first.

• pragmas that specify default libraries
• pragmas that provide auxiliary information used for code generation

16-bit:  Auxiliary Pragmas

16-bit:  Specifying Symbol Attributes

1. a symbol (such as a variable or function)
2. the default set of attributes defined by the compiler

1. Symbol x is assigned the initial default attributes merged with the attributes specified by <attrs_2> and <attrs_3>.
2. Symbol y is assigned the initial default attributes merged with the attributes specified by <attrs_1>.
3. Symbol z is assigned the initial default attributes merged with the attributes specified by <attrs_2>.

16-bit:  Alias Names

where

description

sym

is any valid FORTRAN 77 identifier.

alias

is the alias name and is any valid FORTRAN 77 identifier.

where

description

alias

is the alias name and is any valid FORTRAN 77 identifier.

sym

is any valid FORTRAN 77 identifier.

aux_attrs

are attributes that can be specified with the auxiliary pragma.

16-bit:  Predefined Aliases

__cdecl

__cdecl defines the calling convention used by Microsoft compilers.

__fastcall

__fastcall defines the calling convention used by Microsoft compilers.

__fortran

__fortran defines the calling convention used by Open Watcom FORTRAN compilers.

__pascal

__pascal defines the calling convention used by OS/2 1.x and Windows 3.x API functions.

__stdcall

__stdcall defines the calling convention used by Microsoft compilers.

__watcall

__watcall defines the calling convention used by Open Watcom compilers.

16-bit:  Predefined "__cdecl" Alias

1. All symbols are preceded by an underscore character.
2. Arguments are pushed on the stack from right to left.  That is, the last argument is pushed first.  The calling routine will remove the arguments from the stack.
3. Floating-point values are returned in the same way as structures.  When a structure is returned, the called routine allocates space for the return value and returns a pointer to the return value in register AX.
4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call is made.

16-bit:  Predefined "__pascal" Alias

1. All symbols are mapped to upper case.
2. Arguments are pushed on the stack in reverse order.  That is, the first argument is pushed first, the second argument is pushed next, and so on.  The routine being called will remove the arguments from the stack.
3. Floating-point values are returned in the same way as structures.  When a structure is returned, the caller allocates space on the stack.  The address of the allocated space will be pushed on the stack immediately before the call instruction.   Upon returning from the call, register AX will contain address of the space allocated for the return value.
4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call is made.

16-bit:  Predefined "__watcall" Alias

1. Symbol names are followed by an underscore character.
2. Arguments are processed from left to right.  The leftmost arguments are passed in registers and the rightmost arguments are passed on the stack (if the registers used for argument passing have been exhausted).  Arguments that are passed on the stack are pushed from right to left.  The calling routine will remove the arguments if any were pushed on the stack.
3. When a structure is returned, the caller allocates space on the stack.  The address of the allocated space is put into SI register.  The called routine then places the return value there.  Upon returning from the call, register AX will contain address of the space allocated for the return value.
4. Floating-point values are returned using 80x86 registers ("fpc" option) or using 80x87 floating-point registers ("fpi" or "fpi87" option).
5. All registers must be preserved by the called routine.

16-bit:  Alternate Names for Symbols

where

description

sym

is any valid FORTRAN 77 identifier.

obj_name

is any character string enclosed in double quotes.

where

description

*

is unmodified symbol name

^

is symbol name converted to uppercase

!

is symbol name converted to lowercase

#

is a placeholder for "@nnn", where nnn is size of all function parameters on the stack; it is ignored for functions with variable argument lists, or for symbols that are not functions

\

next character is treated as literal

16-bit:  Describing Calling Information

where

description

sym

is a subprogram name.

const

is a valid FORTRAN 77 hexadecimal constant.

fpinst

is a sequence of bytes that forms a valid 80x87 instruction.  The keyword float must precede fpinst so that special fixups are applied to the 80x87 instruction.

asm

is an assembly language instruction or directive.

16-bit:  Loading Data Segment Register

where

description

sym

is a subprogram name.

where

description

sym

is a subprogram name.

16-bit:  Defining Exported Symbols in Dynamic Link Libraries

where

description

sym

is a subprogram name.

16-bit:  Defining Windows Callback Functions

where

description

sym

is a callback function name.

16-bit:  Describing Argument Information

where

description

sym

is a subprogram name.

reg_set

is called a register set.  The register sets specify the registers that are to be used for argument passing.  A register set is a list of registers separated by spaces and enclosed in square brackets.

16-bit:  Passing Arguments to non-FORTRAN Subprograms