This software is distributed as is.

THIS IS A BETA VERSION OF THIS APPLICATION NOTE, please give us your
suggestions and opinions.


The following disk contains sample code that demonstrates accessing
memory from a Fortran PowerStation application by making calls to the
DOSXNT DOS extender.  The disk contains the following files:


    README.TXT
    LEGAL.TXT	      Description of rights and responsibilities

    DOSX_API.OBJ      !Functions to read and write real memory
    DOSX_API.FI       !Prototypes for the functions in DOSX_API
    API_TEST.FOR      !Fortran program demonstrating the functions

    MAP.OBJ           !Function: re-map memory to physical address
                      ! NOTE: This function fails under DPMI
    TEST.FOR          !Test program for MAP.OBJ

    MEM_ACCS.ZIP      Zip file containing all the other files


There are 2 OBJ files for 2 very different situations:

   DOSX_API.OBJ
     Uses standard API calls
     Works with or without DPMI
     Only accesses real memory (low 1Meg)

   MAP.OBJ
     Does a low-level re-map of memory allowing efficient Peek/Poke
        into physical memory from Fortran
     Only works without DPMI (will not work in a DOS-Prompt under
        Windows)
     Can be used to access any memory location


DOSX_API - Additional Information 

These are the memory access functions:
    ReadMemQQ
    WriteMemQQ

Before making calls to either function, internal data must be
initialized with:
    DosInitInterface
(this function only needs to be called once)

To create the example:
    FL32  API_TEST.FOR  DOSX_API.OBJ

For more information see the FORTRAN example source code API_TEST.FOR,
and the header file DOSX_API.FI.


MAP - Additional Information 

***  This function only works in DOS, not DOS under Windows ***

The following function prototype is required:

      interface to integer*4 function mapmem
     +                       [stdcall,alias:'_MAPMEM@12']
     +                       (addr,memsize,physaddr)
      integer*4 addr[value]
      integer*4 memsize[value]
      integer*4 physaddr[value]                           
      end
                                
ADDR is the address of a PAGE-ALIGNED memory location in the 
application's memory space.  If this is not page aligned 
(mod 4096) then the function will fail.

MEMSIZE is the amount of memory in bytes to be mapped.  It must be a
multiple of 4096.

PHYSADDR is the physical memory location to be mapped in.

The return value is the error status.

  0, no error
  8, if memory error
  9, if invalid memory region (probably not page-aligned).
130, if not supported under DPMI server

The FORTRAN code will need to declare a static or allocatable array
of at least 4K larger then required since there is no way to force
arrays to be page-aligned.  Both the starting memory location passed
into the MAPMEM function (some offset into the array) and the MEMSIZE 
value must be multiples of 4096. Care must be taken that the memory
block starting at logical address ADDR of size MEMSIZE is within
the logical address space of the array.

Once the MAPMEM function has been successfully called then the 
FORTRAN program can proceed to simply read from or write to the array 
that was mapped and the data will be be read from or sent to the 
actual physical memory location.  Care must be taken to write to the 
correct elements in the array since the mapped memory will begin at 
some offset into the array.

For information on how to determine ADDR, MEMSIZE, and the offset, see 
the example TEST.FOR.

To build the example:
   FL32 TEST.FOR MAP.OBJ