4.7.3 Reading Data with uio_dataset_rd.pro or uio_datasetlist_rd.pro

For a detailed description of how to handle UIO files in IDL see Sect 7.

With the new IDL routines uio_struct_rd.pro, uio_dataset_rd.pro, and uio_datasetlist_rd.pro files are not read entry by entry anymore but in larger blocks (or ``data sets'').

With uio_struct_rd all entries in a file are read and put into an IDL structure variable. This is appropriate for the CO5BOLD parameter file or for the UIO table file in Sect. 4.3.3, e.g.

  par=uio_struct_rd('st35gm04n05_03.par')
  atm=uio_struct_rd('holmu.atm')

When groups of entries in an UIO file are properly marked with label dataset and label enddataset delimiters (confer the example in Sect. 5.1) each group can be accessed with uio_dataset_rd. The first block can be read with

  ful=uio_dataset_rd('st35gm04n05_03.full')

or

  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=0)

Dataset number i+1 (counting starts at zero) can be read with

  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=i)

If a dataset with that number does not exist, an empty structure is returned. In this case, when called with additional keywords like

  ful=uio_dataset_rd('st35gm04n05_03.full', ndataset=i, outstr=outstr,ierr=ierr)

an error message is returned in outstr and ierr is set to a value larger than $0$.

To read all entries in a list of files in sequence the routine uio_datasetlist_rd.pro is convenient, as in

model='st33gm06n03' & modelident='_??' & parmodelident='_01'
modeldisk=getenv('HOME') + '/dat/rhd/d' + model + '/'
;
modelfile=modeldisk + model + modelident    + '.full'
parfile  =modeldisk + model + parmodelident + '.par'
;
; --- Read parameter file ---
par=uio_struct_rd(parfile)
;
; --- Open first dataset to get some information about array sizes ---
delvar, listdata
ful=uio_datasetlist_rd(modelfile, listdata=listdata, ierr=ierr)
uio_closrd, listdata.channel
delvar, listdata
;
nxc1=n_elements(ful.z.xc1)
nxc2=n_elements(ful.z.xc2)
nxc3=n_elements(ful.z.xc3)
;
n_timestep=1000  ; --- Some huge value to get everything. Reduce for tests! ---
ierr=0
i=0
;
; --- Loop over all datasets ---
while ((ierr eq 0) and (i lt n_timestep)) do begin &$
  ; --- Read the next dataset ---
  ful=uio_datasetlist_rd(modelfile, listdata=listdata, ierr=ierr) &$
  if (ierr eq 0) then begin &$
    print, '--- ', i, ful.z.itime, ful.z.time, format='(A,I4,I6,E15.8)' &$
    ;
    ; --- Now do the data handling (demo) ---
    print, 'Mean density: ', avg(ful.z.rho) &$
    ;
    i=i+1 &$
  endif &$
endwhile

Note that you can specify an entire group of files with modelident='_??'.