Overview

This tutorial shows you how to use the grd.pro and oldgrd.pro libraries to work with gridded data in grd and grdmap files. The grdmap files are the binary replacements to the grd files. Although the two file types are very different, the IDL interfaces are very similar and return the same data structures regardless of the file being read.

The libraries consist of functions written both in native IDL and functions that act as wrappers and use theCALL_EXTERNAL function to call the C libraries. The native IDL functions are the most portable, but are considerably slower than using the C libraries. The libraries contain a third set of functions that automatically determine whether the native IDL or C library functions should be used; you don't need to worry about which set of functions to use.

Reading grdmap Files

The example program presented below does the simple task of reading records from a grdmap file.

pro readgrdmap

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.grdinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=GridLoadInx(inp,inx)
  free_lun,inp
 
; Open the grdmap file for read only 
 
  inp=GridOpen('test.grdmap',/read)
 

;  Search for a specific time in the file

  s=GridSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while GridRead(inp,prm,stvec,gvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     stop
  endwhile
  free_lun,inp

end

The file is opened using the call to GridOpen if successful, this function returns the logical unit number associated with the file.

The grdmap files can have an optional, associated index file that greatly speeds up searching for specific records. If this file is not available, then a much slower manual search is performed.

The read routine GridRead returns one structure and two arrays. The structure is the parameter block and contains the start and end time of the record and a flag indicating whether the data is in extended format or not. The first array is an array of structures containing information about the contributing stations in the file. The second array is also an array of structures and contains the individual vectors. The contents of these structures are documented in RFC #0023.

Reading grd Files

The example program presented below does the simple task of reading records from a grd file.

pro readgrd

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.inx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=OldGridLoadInx(inp,inx)
  free_lun,inp
 
; Open the grid file for read only 
 
  inp=OldGridOpen('test.grd',/read)
 

;  Search for a specific time in the file

  s=OldGridSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while OldGridRead(inp,prm,stvec,gvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     stop
  endwhile
  free_lun,inp
end

The file is opened using the call to OldGridOpen if successful, this function returns the logical unit number associated with the file.

The grd file may have an associated indexd file that greatly speeds up searching for specific records, if the index file is not supplied a much slower manual search is performed.

Writing grdmap Files

The program presented below is a simple extension to the read program that uses the GridWrite function to write the data to a new file.

pro writegrdmap

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.grdinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=GridLoadInx(inp,inx)
  free_lun,inp
 
; Open the grdmap file for read only 
 
  inp=GridOpen('test.grdmap',/read)
  out=GridOpen('test2.grdmap',/write)

;  Search for a specific time in the file

  s=GridSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while GridRead(inp,prm,stvec,gvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     s=GridWrite(out,prm,stvec,gvec)
  endwhile
  free_lun,inp
  free_lun,out
end

Writing grd Files

The program presented below is a simple extension to the read program that uses the OldGridWrite function to write the data to a new file.

pro writegrd

; Open the raw index file and load it into the inx structure 

  openr,inp,'test.inx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=OldGridLoadInx(inp,inx)
  free_lun,inp
 
; Open the grid file for read only 
 
  inp=OldGridOpen('test.grd',/read)
  out=OldGridOpen('test2.grd',/write)
 

;  Search for a specific time in the file

  s=OldGridSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while OldGridRead(inp,prm,stvec,gvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     s=OldGridWrite(out,prm,stvec,gvec)
  endwhile
  free_lun,inp
  free_lun,out

end