PGPLOT Installation Instructions: Windows 95/NT with PowerStation Fortran

Version 5.2.0

The following notes are based on information received from P. A. Seeger, C. T. Dum, and Joe Walston. Please send any suggestions for improvement to Tim Pearson.

Supported system: Microsoft Windows 95 or Windows NT with Microsoft PowerStation Fortran 4.0. Note: applications developed in this Fortran will not execute under DOS or Windows 3.x (no, not even with WIN32s).

Once PGPLOT.LIB is built, applications are most easily compiled using the Microsoft Developer Studio. The application type must be "QuickWin", or it must be compiled with command line option "/MW". Programs execute in a text window, with the graphical output in up to 8 separate child windows. Cursor functions (including rubber-band modes) are implemented with the mouse.

Installation Instructions

Download PGPLOT by your favorite method from URL:
ftp://ftp.astro.caltech.edu/pub/pgplot/pgplot5.2.tar.gz.
Uncompress the file (gunzip) and extract the files from the tar archive (tar cv). Versions of gunzip and tar for Windows are available on the Web. One program that will handle both steps is WinZip. It is available from http://www.winzip.com and many other web sites.
The files in the tar archive are organized in a hierarchical directory structure, with the top level directory called PGPLOT. You will need the files from the following directories:
```
     x:\PGPLOT
              \CPG
	      \DRIVERS
	      \EXAMPLES
	      \FONTS
	      \PGMF
              \SRC
              \SYS_WIN
```
The other SYS_* directories can be ignored.
The directory PGPLOT\SYS_WIN contains system-specific files for this operating system and compiler:
```
     GRDOS.F
     GREXEC.F
     GRGFIL.F
     GRSY00.F
     W9DRIV.F    (screen driver)
     PGBIND.MAK
```
Delete the file PGPLOT\SRC\GRGFIL.F; use the file GRGFIL.F from this directory instead.
The file GREXEC.F is a device dispatch routine that calls selected PGPLOT device drivers. The distributed version includes device drivers for Windows screen, PostScript files, and the null graphics device. If you want to include additional PGPLOT device drivers, you will need to edit this file before compilation. For more information, see Appendix E.
On your boot disk (almost surely C:), create a directory C:\PGPLOT and copy RGB.TXT to it.
Create the binary font file GRFONT.DAT in this directory. This is done by compiling and running program PGPACK. The source code for this is file PGPACK.F in subdirectory \FONTS (it is a self-contained program). Program PGPACK requires file GRFONT.TXT (also in \FONTS) as its standard input stream; you may need to edit PGPACK.F to open this file explicitly if you cannot redirect the standard input. If PGPACK runs successfully, it will report
```
 Characters defined:   996
 Array cells used:   26732
```
PGPLOT programs need to read files RGB.TXT and GRFONT.DAT at run time. If you put them in a different directory, specify that directory name in the environment variable PGPLOT_DIR; or specify the full [path]filenames dor the two files in environment variables PGPLOT_RGB and PGPLOT_FONT.)
In the Developer Studio, in the File/New menu, Create a new Project Workspace of Type "Static Library", Name PGPLOT, Location x:\MSDEV\PROJECTS\. Use the Insert/"Files into Project..." search box to associate the following files with the project:
```
      x:\PGPLOT\SRC\GR*.F
      x:\PGPLOT\SRC\PG*.F
      x:\PGPLOT\SYS_WIN\*.F
      x:\PGPLOT\DRIVERS\LXDRIV.F,NUDRIV.F,PSDRIV.F
```
(The dependent *.INC files will be included automatically.)
Alternatively, you can compile all the files with the command-line compiler, rather than using the Developer Studio.
Build the project. From the Build menu, choose "Build PGPLOT.LIB". The default compiler options are suitable; in particular, the Debug configuration is not optimized, but the Release configuration uses full optimization. Expect 7 Warning messages. When successfully completed, I like to copy the Release version of the library from x:\MSDEV\PROJECTS\PGPLOT\RELEASE to x:\MSDEV\BIN, where subsequent applications can find it easily.
Run the examples. In the same Project Workspace, use Insert/ "Project..." to Create a project of Type="QuickWin Application", Name EXAMPLES. Then use Build/"Subprojects..." to specify that PGPLOT is a subproject of EXAMPLES. One at a time, use Insert/ "Files into Project..." to select a file from x:\PGPLOT\EXAMPLES. (The previous file may be deleted from the FileView window when successfully completed.) From the Build menu, choose "Execute EXAMPLES.EXE". You may delete all of the PGPLOT folders from x:\MSDEV\PROJECTS after successfully testing the library.
Drivers for Windows95, Postscript, LaTeX, and the Null driver have been included. If you add additional drivers (which may require debugging to eliminate perceived syntax errors etc.) to the library, then subroutine GREXEC.F must also be modified to reflect the changes; in particular NDEV must reflect the total number of drivers.
The default graphic window size for device type "/W9" is 800*600 with 236 colors (SVGA). The default can be changed by setting an environment variable (either in AUTOEXEC.BAT, or from a command line before starting the application) as follows:
```
      SET PGPLOT_VIDEO=VGA  (or V),   640 * 480
                       SVGA (or S),   800 * 600
                       XGA  (or X),  1024 * 768
                       ZGA  (or Z),  1280 * 1024
```
Modes may also be selected by using alternate device types "/WV", "/WS", "/WX", or "/WZ". Modes exceeding the capability of the Windows screen driver will be reduced to the maximum available. For an example of the 236-color modes, see PGDEMO4. For an example of different resolutions, try using "/WV" for the first window and "/WX" for the second window in PGDEMO13.
The cursor is emulated by an interrupt driven mouse routine (see GRW901 in file W9DRIV.F). The cursor moves continuously whenever the window is selected, but the position is not returned to the calling program until a key has been struck, and the character is also returned. Control then returns to the "text" window for any additional input or processing. If you lose track, there is a status message at the bottom of the frame window which tells you which window is waiting for input. The color of the cursor may be dim against some backgrounds (especially green in the default palette), but you can usually see it at the tip of the mouse arrow while you move it around. You might try using PGBAND mode 7 for the cursor to improve visibility. See especially programs PGDEMO5 and PGDEMO6.
Plots can be clipped and copied to other applications, such as Word. Unfortunately, black is black and white is white, so printing uses a lot of ink and the white lines tend to disappear. One option is to exchange palette colors 0 and 1 in PGPLOT with
```
      CALL PGSCR(0, 1., 1., 1.)    ! background color becomes white
      CALL PGSCR(1, 0., 0., 0.)    ! foreground color becomes black
```
before making the version to be printed; another is to cut and paste to a utility (I use Paint-Shop-Pro) in which you can adjust the color palette; and a third way is to specify the "/PS" device and write a file. (Note: this might be a good use for a custom menu entry in your application.) Yet another option is to create a second device window and change the color palette only in that window. (See PGDEMO13 for an example of multiple simultaneous windows.)

Using the C binding

The PGPLOT C binding (cpgplot) allows the Fortran PGPLOT library to be called from C programs, using C calling conventions. The following instructions apply to

C programs compiled with MS Visual C++ V4.0;
calling PGPLOT compiled with MS Powerstation Fortran V4.0;
under MS Windows-95 or Windows-NT.

Other compilers may use different calling conventions and will require a different version of the C binding.

To build the cpgplot binding library, you will need the following files:

	PGPLOT\CPG\PGBIND.C
	PGPLOT\SYS_WIN\PGBIND.MAK
	PGPLOT\CPG\PGBIND_PROTOTYPES

These files can be located anywhere convenient.

To build the library, from a console (DOS) window type

	 NMAKE /F PGBIND.MAK

This will create cpgplot.lib and cpgplot.h.

The makefile compiles pgbind.c (no unusual compiler flags are needed) to produce the pgbind program. It then produces the C wrapper functions (one file per wrapper) and the cpgplot.h header file using:

   pgbind ms -w -h pgbind_prototypes

The cpg*.c files are then compiled and gathered into a library.

To use cpgplot in your programs, you should include cpgplot.h at the top of all C files that use cpgplot functions, and link your programs with both of cpgplot.lib and pgplot.lib.

For further information about using the C binding, see file

  PGPLOT\CPG\CPGPLOT.DOC

or the Web page

  http://www.astro.caltech.edu/~tjp/pgplot/cbinding.html