Getting Started with X/Win32 GrADS

Version 1.8SL11

GrADS logoDAO logo

Last Update: December 5, 2002

Contents

Introduction

X/Win32 GrADS is a port of Brian Doty 's popular Grid Analysis and Display System (GrADS) to the x86 PC running 32-bit MS Windows operating sytems (win9x, winNT, win2000), and using an X Server.

This implementation of X/Win32 GrADS is functionally equivalent to all Unix versions. Supported features include:

Choosing a PC Version of GrADS

The Table below compares some of the features available with the different PC versions of GrADS:
 
Feature
X/Win32 GrADS
Win32e GrADS
PC/X11e (MSDOS)
Command line editing (readline) X X (partial)
NetCDF support X X X
HDF support X X  
DODS support X  X  
LATS X X X
Athena Widget GUI X    
Image Magick (wi command) X    
Image printing (printim command) X X X

As can be seen, this version (X/Win32 GrADS) has all of the functionality found in the Unix versions of GrADS. However, it requires the installation of an X server. Win32e GrADS does not require an X server, but currently lacks  Athena GUI and Image Magick support which may be required by some users. The MS-DOS version of GrADS is the least featured; however it has the fastest graphics and runs well on low end PCs (I've heard of users running it on ancient 386 boxes). The choice is yours. The choice is yours. For GrADS download information, consult http://grads.iges.org/grads/downloads.html  .

Note: The directory structure of the PC GrADS binaries is designed in such a way that all PC versions could be installed on the same machine, sharing the same dat/ (fonts and map datasets) and lib/ (script library) directories. The particular version of "grads" to be executed would depend on how you have your PATH set.
 
 

System Requirements

X/Win32 GrADS is a 32-bit application. You must have the following hardware/software:

This Distribution

In this installation you will find the following sub-directories: Sample data files are not included in this distribution; a small collection of sample gridded and station data files can be downloaded from ftp://grads.iges.org/grads/sprite/tutorial/ . The GrADS binaries and executables in win32/ as well the documentation files under doc/ are further described below. We start with the necessary X Server setup.

X Server Setup

Because X/Win32 GrADS is based on the same code as the Unix version, it requires an X server. An X server is the software which processes instructions from "X clients" such as GrADS to do things like draw on the screen. X/Win32 GrADS has worked with a wide variety of X servers. Here are a few options:


Using X/Win32 GrADS

Now that you have installed your X Server you are ready to go. Start your X server, and from the Start menu, click on Programs, and then click on Win32 GrADS. If you are new to GrADS you may want to start with the GrADS Tutorial .

Very Important: You must start your X server before running GrADS, it is not enough to install it.

The following applications are available.
 


Application Description
Grads Win32 GrADS with the classic command line interface (ga-> prompt).  This version is the same as GradsDODS below and can read and write NetCDF files (but no HDF-SDS files); see sdfopen , xdfopen . 
GradsC  Win32 GrADS with the classic command line interface (ga-> prompt), but without NetCDF/HDF-SDS, LATS, Athena GUI or Image support through the wi command. This version can read IEEE and GRIB files. This is the smallest version of Win32 GrADS and requires the least amount of memory. 
GradsGUI  Win32 GrADS with a Graphical User Interface based on the Athena Widgets . This version automatically starts the gui script sample2.gui , otherwise it is the same as GradsDODS below. 
GradsHDF  Win32 GrADS built with NCSA's MFHDF (Multi-file HDF) library. With this configuration GrADS can read both NetCDF and HDF-SDS files (see sdfopen , xdfopen ), but can only write HDF-SDS files (but cannot write NetCDF files). IEEE and GRIB files are fully supported. 
GradsNC  Win32 GrADS built with Unidata's NetCDF library. With this configuration GrADS can read (see sdfopen , xdfopen ) and write NetCDF files, but cannot handle HDF-SDS files. IEEE and GRIB files are fully supported. 
GradsDODS  Win32 GrADS built with Unidata/URI DODS NetCDF client library. With this configuration GrADS can read (see sdfopen , xdfopen )  NetCDF and remote DODS files, and write NetCDF files. While it cannot handle HDF-SDS files, IEEE and GRIB files are fully supported. This is the version of GrADS requiring the most memory. 
Gv32  Windows' based GrADS metafile viewer.
Gxtran Classic metafile viewer (Gv is nicer).
Gxeps Converts GrADS metafiles to enscapsulated postscript (faster). You may want to obtain the Windows version of Ghostview (gsview), freely available from http://www.cs.wisc.edu/~ghost/gsview/. Gsview will allow you to preview and print PostScript documents on win95/NT. Highly recommended.
Gxps Converts GrADS metafiles to postscript level 1 (slower) 
Gribmap GRIB file mapping utility 
Gribscan GRIB file scan utility 
Wgrib Wes Ebisuzaki's GRIB utility (it slices, dices) 
Stnmap Station mapping utility 
Ncdump Convert NetCDF/NDF-SDS files to ASCII form (CDL). For source code and additional information consult http://www.unidata.ucar.edu/packages/netcdf .
Ncgen From a CDL file generate a netCDF file, a C program, or a Fortran program. For source code and additional information consult http://www.unidata.ucar.edu/packages/netcdf .
HDFdump Similar to Ncdump , but can read HDF-SDS files. Note: avoid using this utility for NetCDF files due to a bug related to packed NetCDF files. For source code and additional information consult http://hdf.ncsa.uiuc.edu.
Hdfgen  Similar to Ncgen , but output is in HDF-SDS format.For source code and additional information consult http://hdf.ncsa.uiuc.edu.
sh Win32 port of the GNU Bourne Again Shell (bash). This utility is needed for executing shell commands from grads, e.g., ! ls. For documentation of GNU software consult http://www.gnu.org/doc/doc.html. For source code and additional information, consult http://www.cygnus.com/gnu-win32. 
rxvt A nice terminal for replacing Windows COMMAND.COM. You can start Grads under rxvt by entering: 

rxvt -fn fixedsys -fg darkgreen -e Grads 

NOTE: For running rxvt as a standalone program you may need to create the directory c:\cygwin\tmp .
ls, cp, rm. mv, pwd, cat Assorted GNU file utilities to facilitate porting GrADS scripts from Unix to Win32. For documentation of GNU software consult http://www.gnu.org/doc/doc.html For source code and additional information, consult http://www.cygnus.com/gnu-win32. 
convert , display , animate , import , montage , mogrify , identify , combine Image Magick tools . For source code and additional information consult http://www.wizards.dupont.com/cristy/ . A local copy of this page is available here . Before using display and other Image Magick applications be sure to set the environment variable DISPLAY=localhost:0.0. 
*.dll  These are Dynamic Link Libraries (DLL) needed by the applications above. If you move them to a different directory, make sure they remain in your PATH. The DLL files above are usually not visible from the Win32 GrADS Program Group. You can change this default behavior from the View/Properties menu of the Windows Explorer. 

You can also start Win32 GrADS or any of the applications above from the DOS command line, e.g.,

c:\> grads
Recall that DOS is case insensitive, so grads is the same as GrADS. You may want to put the GrADS binary directory (usually c:\progra~1\pcgrads\win32 ) on your path. See rxvt above for a nice terminal program for Windows.

Documentation

The sub-directory doc/ contains several documentation files of interest.
 
Document
Description
User's Guide As of version 1.8, an on-line version of the GrADS User's Guide is available.  For convenience a copy is also provided here, along with an alphabetical index. It is recommend that you consult the on-line version for up to date information. A tutorial is also available.
cards/ Quick reference cards for GrADS commands and GrADS scripting language in PostScript, both in A4 and US Letter sizes: 
  • refv1.7-a4.ps -GrADS reference card (DIN A4) 
  • refv1.7-scl-a4.ps - GrADS scripting language reference card (DIN A4)
  • refv1.7-letter.ps -GrADS reference card (US Letter)
  • refv1.7-scl-letter.ps -GrADS scripting language reference card (US Letter) 
Thse cards are contributed by Karin Meier-Fleischer (meier-fleischer@dkrz.de). The official site for these cards is ftp://ftp.dkrz.de:/pub/visu/grads/doc .

You may want to obtain the Windows version of Ghostview (gsview), freely available from http://www.cs.wisc.edu/~ghost/gsview/. Gsview allows you to preview and print PostScript documents on win95/NT. Highly recommended. 
gagui/ Using GrADS with Athena Widgets , HTML document
magick/ ImageMagick documentation.
etc/  Unix style manual pages/text documents for several utilities: 
  • grads.html - GrADS Unix manual page for version 1.6.beta.4. Please notice that there is no need for setting the environment variables GADDIR, GASCRP, etc in this WIn32 version.
  • grib.txt - Text file with information about working with GRIB files 
  • grib2ctl.html - Local copy of grib2ctl home page. 
  • grib2ctl.txt - Text documentation for grib2ctl
  • gribmap.html - Unix manual page
  • gribscan.html - Unix manual page
  • gxeps.html - Unix manual page
  • gxps.html - Unix manual page
  • gxtran.html - Unix manual page
  • proj.txt - Text file with information about working with map projections 
  • ncdump.html - Unix manual page
  • ncgen.html - Unix manual page
  • outxwd.txt - Describes the outxwd command which produces an X window dump of the GrADS graphics screen
  • stnmap.html - Unix manual page
  • wgrib.html - Local copy of wgrib's home page
  • wgrib.txt - Text documentation for wgrib

Using GrADS with Athena Widgets

Starting with version 1.7, GrADS provides a simpler way for creating widgets (graphical user interface) from a user defined GUI script. A GUI script included in this distribution alllows you to build the following user Graphical User Interface for GrADS:

For additonal information consult the document Using GrADS with Athena Widgets .

Notes:

  1. If you are familiar with X11 widgets build with "gs" scripts, note that this is a completely different set of functions for building event driven widgets. Currently, there is a separate script processor (the gui command available from the ga-> prompt) for handling these functions. The Win32 application GradsGUI automatically starts a GUi script for you; try it!
  2. This is an experimental version: both the scripting language as well as the available callbacks may change in the near future.
  3. Although it does not crash the free X server from Micro Images, the menu items become invisible when you try to select it (this is due to a bug in the MI/X server). This feature works much better with the X-Win32 server from StarNet.
  4. You can also add a graphical user interface (GUI) to GrADS by using the XGrads package based on tcl/tk. This package has been shown to run on Win32. For more information, take a look at:
    5. ftp://cola.iges.org/grads/sprite/XGrads/xgrads.win32.tar

Getting Help

A list server is available for GrADS users to exchange information on problem solving, script refinements, user defined functions, etc. Messages typically contain requests for help and ideas for solutions from users who have faced similar problems. Reference is frequently made to upgrades to GrADS and how to obtain them. All posts to the listserver are automatically dispatched to all subscribed users. In order to keep out spammers and internet marketers, subscription is no longer automatic. Send an email to the address below giving your affiliation, electronic and postal addresses, phone, etc. and you will be added by the system administrator.

To join, send email to: gradsusr-request@list.cineca.it

Once subscribed, carefully read and archive the important information regarding the use of the listserver and how to send messages. Before posting to the listserver, check the online archive to see if your question has already been answered. 

When reporting bugs or problems, please include the following information in your post: 
  1. The version of GrADS you are running (it is a good idea to include all the output from 'q config') 
  2. The platform you are running GrADS on (e.g. SunOS, DEC Alpha, Windows95...) 
  3. A brief description of the problem 
  4. The simplest possible script that illustrates the problem 
  5. The error messages from GrADS 
  6. The output from running "ncdump -c" on your NetCDF file if you're having trouble getting GrADS

    7. to read the file. 
If nobody responds to your post, it may be because you didn't provide enough information. In order to get the answers you want from the GrADS community, you have to ask the questions in the right way. Of course, it may also be the simple case that nobody has an answer.If a week has gone by and there is still no reply, try reposting again, making sure that you've included all the items from the list above, and noting that it is your 2nd request. 

Acknowledgements

This Win32 port was contributed by Arlindo add Silva from the Data Assimilation Office (NASA/GSFC). X/Win32 GrADS is built with the Cygwin tools and the X Client Libraries provided by Cygwin/Xfree86 Project. The wi command is implemented through an interface to ImageMagick API; ImageMagick is written by John Cristy. Mike Fiorino provided invaluable help during the initial phase of this port. Don Hooper helped porting the SDF interface; Steve Emmerson provided guidance with UDUNITS. Brian Doty tested some of the grads widget features. Many thanks to all.

| DAO Home Page | DAO Reanalyses | DOLMS | DAO People | GrADS Home Page |

Data Assimilation Office / Code 910.3 / NASA - Goddard Space Flight Center

 

 

Office Head: Robert Atlas
Page Author: Arlindo da Silva