The following notes are reproduced from an earlier version of PGPLOT.
PGPLOT v5.0 has not yet been ported to MS-DOS. Neither I nor Allyn
Tennant has the resources to do this. Anyone planning to try to port
PGPLOT to MS-DOS should contact me before doing so, to avoid
duplication of effort.

The makefile in this directory is not complete, but may serve as a
model.

Tim Pearson
30 December 1994
------------------------------------------------------------------------


                   PGPLOT on an MS-DOS machine 
                        Allyn F. Tennant
                   Marshall Space Flight Center
                          1991-Jun-30

This this directory contains all the files needed to get PGPLOT to
compile with Microsoft Fortran 5.0 (or later) using the huge memory
model.  Earlier versions of Microsoft Fortran do not support the INCLUDE
statement, and also do not come with the GRAPHICS library.  The current
code was tested on a 286 machine with a floating point co-processor
and an EGA display.  The code should support other configurations.

If you are using another Fortran compiler then it is unlikely that
you will be able to directly use the files in this directory.  However,
the files included here will give you some idea of what you will need
to port.  Writing a new device handler is the only thing that might
be difficult.  There are many books that provide routines for drawing
lines on an IBM PC screen that can be included in a device handler.
For example, see the routines in "Programmer's Guide to the EGA/VGA"
by George Sutty and Steve Blair (Simon & Schuster, 1988).  It is a
simple matter to write a device handler that uses these routines.
Due to copyright these routines cannot be provided.


GETTING THE FILES TO THE MS-DOS MACHINE

There are two ways to get PGPLOT on to an MS-DOS machine.  First,
you can use KERMIT (or your favorite file transfer method) to copy
the various directories from a UNIX machine to the DOS machine.  If
you do this you should try to preserve the directory structure from
a UNIX system, thus files from pgplot/sys_dos should be placed in
PGPLOT\SYS_DOS.  The second method involves using the AIX access package
from IBM.  We have a IBM RS/6000 machine and AIX Access allows us
to mount the IBM disks on the DOS machine.  With this method it is
not necessary to move any files.

UNIX terminates lines with a linefeed character whereas DOS uses the
double character sequence return/linefeed.  Much DOS software cannot
cope with the UNIX record structure, however, the Microsoft Fortran
seems to be able to compile files where the lines terminate with only
a linefeed character.  Should you need to convert two AIX routines
are provided for file conversion.  The routine 2aix will strip any
extra return characters, effectively converting the file to UNIX format.
Likewise 2dos will append a return character to every line the file
converting to DOS format.

Note, do not worry about the file extensions.  The current version
of MAKEFILE.DOS can cope with either *.F (typical UNIX) or *.FOR
(needed by DOS).  The makefile works by copying the *.F file into
an *.FOR file, compiling, and then deleting the *.FOR file.


TESTED DRIVERS

Currently only the following drivers have been tested under MS-DOS:

/NULL to plot onto the null device.

/MSOFT to use the Microsoft graphics library routines to plot onto
supported graphics displays.  This driver has only been tested with
an EGA display but should work with other types.  Currently, the cursor
is not supported.

/PS    to produce a file that can be printed on a Postscript printer.

/VPS   to produce a 'vertical' or portrait mode Postscript file.


BUILDING THE LIBRARY

The directory PGPLOT\SYS_DOS contains the source code for GRSY00.FOR
contains the name and path of the font file.  The default location
for the font file is given by:

      PARAMETER  (UNIX='C:\lib\grfont.dat')

If you do not like that location, then you should modify this file to
contain the location where you will keep the font file.  The environment
variable PGPLOT_FONT can be used to override this location at run time.
If PGPLOT cannot find the font file, then plots will still be drawn,
but without labels or markers.

If you are using AIX Access, then on the IBM side you should copy
pgadvance.f to pgadvanc.f.  This is because the NMAKE file includes
this file and (of course) DOS only allows 8 letter file names.

Next, copy the file MAKEFILE.DOS from PGPLOT\SYS_DOS to the PGPLOT
directory.  Then in that directory type:

NMAKE -F MAKEFILE.DOS
NMAKE -F MAKEFILE.DOS

and go out to lunch (actually on a 286 using AIX Access it takes about
2 hours for the above to complete).  About half way through the
execution of the first NMAKE, DOS announces that it cannot load
FL.  I think the problem is DOS runs out of memory keeping track of
what has already been made.  Starting over seems to free up enough
memory so that NMAKE should complete.  If you are low on memory, then
I would not be surprised if NMAKE fails to finish on the second try.
All I can say is keep trying (or better yet trade in your DOS machine
for a real computer).


PGPLOT ENVIRONMENT VARIABLES

As mentioned above, you can override the location of the FONT library
at run time by setting an environment variable.  For example,

SET PGPLOT_FONT=C:\LIB

would cause PGPLOT to look in the C:\LIB directory for the GRFONT.DAT
file.

MS-DOS does not support user-ids, and therefore if you want a user-id
to appear on your plots when PGIDEN is used, then you should define
the environment variable PGPLOT_USER.  For example, I include the
following line

SET PGPLOT_USER=TENNANT

in my AUTOEXEC.BAT file.


TRY THE DEMO PROGRAMS

Currently PGDEMO3.EXE will link but not run.  It is too big to fit
into the 8088 address space that DOS uses.  However, all the other
PGDEMOx and PGEXxx programs should run.

Note, if you are using the /MSOFT device, then the PC will be left
in graphics mode.  This allows the graph to remain after the program
exits.  If you would like to return to text mode, you should use a
command like:

MODE CO80


LINKING WITH THE PGPLOT LIBRARY

You will notice that the MAKEFILE compiles the code with the /Gt option.
The Microsoft Fortran compiler default is to place all variables and
arrays greater than 32K into a common segment.  At link time, the
sum of all these common areas (one for each subroutine) cannot exceed
64K (I believe the error is L1072, but have forgotten).  When this
problem occurs, the only solution is to re-compile enough routines
with a smaller threshold value (and for a package consisting of over
100 routines, this could be a lot of routines).  Using /Gt (with no
number) reduces the threshold size to 256 bytes.  (Actually to be
extra safe, you should trade in your machine for a computer that has
never heard of 64K segments).

The linker always looks in the directory specified by the LIB
environment variable.  If you copy PGPLOT to that directory then the
following command line should work:

LINK /SEGMENTS:256 prog.obj,,NUL,PGPLOT+GRAPHICS;

where object is the name of the object module(s) that you have
previously complied.  GRAPHICS is the name of the Microsoft graphics
library supplied with Fortran 5.0 and is required if you wish to use
the Microsoft device handler (MSDRIV.FOR).  With the huge memory model,
each subroutine is compiled into a separate segment.  A complicated
program can easily contain calls to more than 128 routines (the default
maximum number of segments).  Therefore you are encouraged to use
the /SEGMENTS:256 to increase this default.
