Getting Started with Win32 GrADS

Version 1.9.0-rc1

     

Last Update: 07 April 2008

Contents

Introduction

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 systems. Starting with v1.9. Win32 GrADS is now bundled with the Xming X Windows server, so there is no need to install a separate X server.

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

The following features are no longer supported:

·        ImageMagick interface through the wi command. Both printim and gxyat are better solution although they do not support the vast number of formats wi did.

·        Win32e (built in X11 emulation) and PC/X11e GrADS (MSDOS) are no longer supported. 

System Requirements

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:

The GrADS binaries and executables in win32/ as well the documentation files under doc/ are further described below.

Batteries included

Because 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. Starting with Version 1.9, the excellent Xming X Server

 

http://www.straightrunning.com/XmingNotes/ 

http://sourceforge.net/projects/xming

 

is bundled and integrated with Win32 GrADS. There is no longer a need to install a separate X server. The Xming X server is developed and maintained by Colin Harrison, being derivative from a number of other open source projects. The binaries included with Win32 GrADS are based on the Xming Sourceforge Public Domain Release. See COPYRIGHT notice under subdirectory Xming/ and URLs above for additional information.

 

Note: In the past Win32 GrADS has worked with a wide variety of X servers. If for some reason you would like to work with your trusted X server simply remove or rename the Xming directory shipped with Win32 GrADS and set your DISPLAY environment variable as required by your X server (usually DISPLAY=localhost:0.0). By default, when Xming is present, the GrADS binaries automatically set DISPLAY=localhost:7.0, and starts Xming on Display number 7.

Installation

Up to date installation information can be found on the OpenGrADS Wiki.

Using the Automatic Installer

Installing the Windows version of GrADS is very easy. If you downloaded a file called grads-1.9.x-win32_superpack.exe simply run it, answer a few simple questions, and you are good to go (the installer will also automatically set your PATH so that you can run GrADS from the command line window).

Using the ZIP File

If your distribution came in the form of a zip file, simply unzip the distribution file grads-1.9.x.win32_superpack.zip to a place of your choice (e.g., under C:\ or C:\Program Files\) and you are ready to go. Then open Windows Explorer and click on any of the executables under PCGrADS/win32 (say, grads) and start using it.

Setting your PATH

This step is only necessary if your distribution came in the form of a ZIP file. You may find convenient adding the GrADS binary directory (e.g., C:\PCGrADS\win32) to your PATH. For changing your path click on

[Start]/[Control Panel]/[System]

Then select the [Advanced] tab and click on the [Environment Variables] button on the lower left. Select Path under -System Variables- and click on the [Edit] button. Do not delete the current contents of your path; simply append a ";" followed by the name of the directory where your GrADS binaries reside.

Getting more fonts

The Xming server bundled with Win32 GrADS comes with a minimal number of built-in fonts, plus whatever Windows fonts it may find. This is usually fine since GrADS draws its own fonts and does not rely on the X server for writing strings. The only exception is if you are using the Athena Widgets feature, which does make use of X Window fonts. You can install additional Xming fonts from their Sourceforge download page:

   http://sourceforge.net/project/showfiles.php?group_id=156984

When installing the fonts make sure you install them with the Xmingthat came with your Win32 GrADS distribution, not the suggested default C:\Program Files\Xming. For example, if you installed GrADS under C:\PCGrADS, you will want to install the extra fonts under C:\PCGrads\Xming.

Using Win32 GrADS

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) 

gxyat

Converts GrADS metafiles to Postscript, PDF, PNG and SVG. The PNG images have nice anti-aliased fonts without those funny horizontal lines.

Gribmap

GRIB file mapping utility 

Gribscan

GRIB file scan utility 

Wgrib

Wes Ebisuzaki's GRIB utility (it slices, dices) 

Stnmap

Station mapping utility 

cURL

cURL is a command line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS and FILE.

ncdump,

ncdump-dap, ncdump-hdf, ncdump-nc4

Convert NetCDF/HDF-SDS files to ASCII form (CDL). For source code and additional information consult http://www.unidata.ucar.edu/packages/netcdf .

The -dap, -hdf and -nc4 are versions produced with the OPeNDAP, HDF-4 and NetCDF-4 libraries.

ncgen,

ncgen-hdf, ncgen-nc4

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 .

The -hdf and -nc4 are versions produced with the HDF-4 and NetCDF-4 libraries.

Sh, tcsh

sh is awin32 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://cygwin.com.

tcsh is a port of the C-shell to 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, grep, gzip, etc.

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://cygwin.com

*.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:\> gradshdf

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) 

These 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

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

The OpenGrADS Extensions

As a preview of a feature to be available in GrADS Version 2 we have included some sample User Defined Commands (UDCs) and User Defined Functions (UDFs) implemented as dynamically linked libraries (DLLs) as part of the OpenGrADS Project. These functions and commands are coded in C and Fortran and do not involve the disk transfer files of the classic UDFs.  The following extensions are included in this distribution:

Consult the OpenGrADS Wiki for a detailed description of this feature and documentation of the above extensions.

OpenGrADS Interfaces

This version of GrADS fully supports the Perl and Python interfaces being developed by the OpenGrADS Project. However, the specific Perl and Python modules are not included as they need to be installed in the context of specific Perl/Python distributions. Please consult the OpenGrADS Wiki for additional information.

 

Troubleshooting

  1. It says that Xming is starting up but the graphics window never comes up. Both GrADS and the Xming server uses the local network to talk to each other. If your Windows Firewall or anti-virus software is preventing programs from accessing the network you will not be able to see any graphics on the screen (although GrADS may function OK in batch mode). The solution is to reconfigure your firewall/antivirus software to allow Xming/GrADS to access the local network.
  2. I have a previous installation of X/Win32 GrADS and there is some kind of conflict involving the cygwin1.dll.   This a common problem and of simple solution. The easiest thing to do is to uninstall the previous version of GrADS. Or else, make sure that the directory where the previous version binaries reside is not on your path. There is a good chance (test it first) that the previous version of GrADS will work with the newer cygwin1.dll. In this case, remove or rename the older cygwin1.dll and see what happens.
  3. I am a regular cygwin user and the included cygwin.dllis conflicting with my cygwin installation. See the discussion above. If you have an older cygwin installation, you may want to update that first. If your cygwin installation is newer than the version shipped with GrADS, you may want to remove the cyg*.ddl files included in the PCGrADS/win32/ directory and stick with the ones in your newer cygwin distribution. If all else fails, download the cygwin version of the supplibs and the GrADS sources and rebuild. See instructions in the OpenGrADS Wiki.

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

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 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.

 

To unsubscribe, send an email containing the message "SIGNOFF GRADSUSR" to listserv@list.cineca.it 

Credits

This Win32 port was contributed by Arlindo da Silva (dasilva@opengrads.org). Win32 GrADS is built with the Cygwin tools and the X Client Libraries provided by Cygwin/X Project. The Xming server is developed and maintained by Collin Harrison.

 

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.  

 

GrADS License Terms

The Grid Analysis and Display System (GrADS) Version 1.9

Copyright (C) 1988-2007 by Brian Doty and the Institute of Global Environment and Society (IGES). 

 

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; using version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

See file COPYRIGHT for additional information.