Overview

This tutorial shows you how to use the cnvmap.pro and oldcnvmap.pro libraries to work with convection map data in map and cnvmap files. The cnvmap files are the binary replacements to the map 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 cnvmap Files

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

pro readcnvmap

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

  openr,inp,'test.cnvinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=CnvMapLoadInx(inp,inx)
  free_lun,inp
 
; Open the cnvmap file for read only 
 
  inp=CnvMapOpen('test.cnvmap',/read)
 

;  Search for a specific time in the file

  s=CnvMapSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while CnvMapRead(inp,prm,stvec,gvec,mvec,coef,bvec) 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 CnvMapOpen 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 CnvMapRead returns one structure and up to five arrays, depending on the contents of the file. The structure is the parameter block. 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 third array is an array of structures that contain the model vectors if applicable. The fourth array consists of the coefficients of the fit. The final array contains the boundary of the fit. The contents of these structures are documented in RFC #0023 and RFC #0024.

Reading map Files

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

pro readmap

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

  openr,inp,'test.inx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=OldCnvMapLoadInx(inp,inx)
  free_lun,inp
 
; Open the map file for read only 
 
  inp=OldCnvMapOpen('test.map',/read)
 

;  Search for a specific time in the file

  s=OldCnvMapSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while OldCnvMapRead(inp,prm,stvec,gvec,mvec,coef,bvec) 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 OldCnvMapOpen 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 cnvmap Files

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

pro writecnvmap

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

  openr,inp,'test.cnvinx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=CnvMapLoadInx(inp,inx)
  free_lun,inp
 
; Open the cnvmap file for read only 
 
  inp=CnvMapOpen('test.cnvmap',/read)
  out=CnvMapOpen('test2.cnvmap',/write)

;  Search for a specific time in the file

  s=CnvMapSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while CnvMapRead(inp,prm,stvec,gvec,mvec,coef,bvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     s=CnvMapWrite(out,prm,stvec,gvec,mvec,coef,bvec)
  endwhile
  free_lun,inp
  free_lun,out

end

Writing map Files

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

pro writemap

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

  openr,inp,'test.inx',/GET_LUN,/STDIO,/SWAP_IF_BIG_ENDIAN
  s=OldCnvMapLoadInx(inp,inx)
  free_lun,inp
 
; Open the map file for read only 
 
  inp=OldCnvMapOpen('test.map',/read)
  out=OldCnvMapOpen('test2.map',/write) 


;  Search for a specific time in the file

  s=OldCnvMapSeek(inp,2002,12,19,0,30,10,inx,atme=atme)
 
  while OldCnvMapRead(inp,prm,stvec,gvec,mvec,coef,bvec) ne -1 do begin
     print, prm.stme.hr,prm.stme.mt,prm.stme.sc
     s=OldCnvMapWrite(out,prm,stvec,gvec,mvec,coef,bvec)
  endwhile
  free_lun,inp
  free_lun,out
end