======================================================================
HF0258: Key Entry Functions with FORTRAN and MASM 5.1
======================================================================
Revision Date: 7/91
--------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an |
| Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A |
| PARTICULAR PURPOSE. The user assumes the entire risk as to the |
| accuracy and the use of this Application Note. This Application |
| Note may be copied and distributed subject to the following |
| conditions: 1) All text must be copied without modification and |
| all pages must be included; 2) If software is included, all files |
| on the disk(s) must be copied without modification [the MS-DOS (R) |
| utility DISKCOPY is appropriate for this purpose]; 3) All |
| components of this Application Note must be distributed together; |
| and 4) This Application Note may not be distributed for profit. |
| |
| Copyright 1991 Microsoft Corporation. All Rights Reserved. |
| Microsoft, MS-DOS, and the Microsoft logo are registered |
| trademarks of Microsoft Corporation. |
--------------------------------------------------------------------

This application note contains two examples of simple key fetch
routines written in Microsoft Macro Assembler (MASM) version 5.1 for
use with Microsoft FORTRAN versions 5.0 and 5.1. These routines use
DOS interrupts and do not work under OS/2 or Windows.

Example A contains a function that when called, waits for a keystroke
and then passes back the keystroke character to the FORTRAN calling
program. This function can be used to obtain single-keystroke
information from you without requiring you to press the ENTER key.

Example B contains a function that does not wait for you to enter a
keystroke but reports if a keystroke has been previously entered. You
do not need to press the ENTER key for single-key data to be accepted.

The assembly functions that call examples A and B were not designed
for redirected standard input. Furthermore, the interface routine is
currently set up only to flag that a function or ALT+key sequence was
entered and to print a message accordingly, where key is any key on
the keyboard.

To retain the full function names, make sure neither the /4Yt compile
switch nor the $TRUNCATE metacommand is used when compiling these
routines. FORTRAN versions 4.x use these switches as defaults; thus,
the $NOTRUNCATE metacommand must be used.

.OBJ files can be added to the FORTRAN run-time library by using the
LIB.EXE utility provided with the FORTRAN package. MASM is required
to reassemble the assembly source code on the disk included with this
application note if modified versions of these procedures are desired.

Example A
----------

The following describes the three pieces of code included on the
enclosed disk that are for use with example A:

1. \EXAMPLEA\AMAIN.FOR -- The main program. In this program, the
GETCH ("get character") function is called to retrieve the
keystroke. The keystroke is returned as a character*1 value.

2. \EXAMPLEA\AINTER.FOR -- The GETCH ("get character") function.
This function includes the interface statement for the assembly
routine and also calls the assembly function. The integer value
returned by the assembly function is converted to a character using
the CHAR intrinsic function. Although the interface statement is
unnecessary when linking with assembly procedures, this
intermediate routine is useful because it contains the integer-to-
character conversion, eliminating the need to convert in the main
program. The advantage to converting with the GETCH function is
that GETCH can be added to the FORTRAN run-time library using the
LIB.EXE utility; therefore, GETCH can be called from any program,
preventing you from having to include a conversion statement every
time a program uses the getchasm 1assembly routine.

3. \EXAMPLEA\AMASM.ASM -- The getchasm function. This is the
assembly procedure that calls DOS interrupt 21, function 1, which
inputs a character with echo to the screen. Interrupt 21, function
1 can be replaced with interrupt 21, function 7, which inputs a
character without echo to the screen. Replacing interrupt 21,
function 1 with interrupt 21, function 7 requires the procedure to
be reassembled with MASM.

Example B
---------

The example B code does not wait for keyboard input but retrieves the
keyboard character if a keyboard character was entered. Characters
are not echoed to the screen upon entry, which is useful for password
input.

1. \EXAMPLEB\BMAIN.FOR -- The main program. In this section, the
GETCH ("get character") function is called to retrieve a keystroke.
If you enter a keystroke, the keystroke character is displayed
along with the loop number in which the routine returned a result.
If no keystroke is entered, the program continues looping.

2. \EXAMPLEB\BINTER.FOR -- The GETCH ("get character") function.
This function is the same as AINTER.FOR in example A.

3. \EXAMPLEB\BMASM.ASM -- The getchasm function. This is the
assembly procedure that calls DOS interrupt 21, function 0Bh to
check if a keystroke has been entered. If a keystroke has been
entered, the procedure calls function 06h, which retrieves the
keystroke character and returns. If no keystroke has been entered,
the assembly procedure returns to the main program.