6.2.7 IDL UIO routines

The UIO package for IDL comes as a list of routines with names quite similar to the Fortran90 version. Instead of using global variables as in Fortran90 there are now common blocks in Include-files.

;****************************************************************************** ; Routines, functions : uio_*.pro: ; (!: most important, +: user-routine, -: comfortable, .:useful) ; . adkey1: Add one keyword to term table, keyword-value=' ', no link character ; . adkey2: Add one keyword to term table with keyword-value ; . adkey3: Add one keyword to term table with keyword-value or default ; . chconv: Actualize list of conversion types for all channels ; + chpos: Give current file position or jump to specified position ; . chunit: Initialize, store and actualize a list of free and occupied unit ; numbers ; + closrd: Close file after reading ; + closwr: Close file after writing ; - cpentr: Copy entry from one file to another ; + d: Read data from uio-file(s) in quasi direct-access mode ; + data: Handle uio-file(s) in quasi direct access mode ; ! dataset_rd: Read uio file and put data into anonymous structure ; ! datasetlist_rd: Read data from list of files and put it into an. structure ; deform: Determine the default output format for numbers ; dim2st: Compose dimension string ; . exkeyw: Extract value of keyword from table ; ex1trm: Extract one term from the input line ; exmtrm: Transform a list of items into its components ; . filcon: Determine file contents: list of all entries with its positions ; getenv: Get information about environment ; ! init: Initialization procedure for input/output routines ; me1trm: Merge the input term: 'keyword', 'value' -> 'keyword=value' ; memtrm: Merge a list of terms (keywords and their values) into a line table ; mkcvls: Make list with possible conversion types ; . nc2nt: From column number or entry name find table entry number ; + openrd: Open file for reading, read header ; + openwr: Open file for writing, write header ; - pptrmt: Print term table in pretty form ; qmaadd: Transform a string into a string with quotation marks if necessary ; qmadel: Parse string "inline" and remove quotation marks if necessary ; + rd: Reading scalar and array data of all types ; . rdfifo: Read file header ; + rdhdex: Read header of variable and extract keywords ; rdhead: Read header ; + rdlabl: Read label ; + rdtab: Read table of integer, real, and/or character data from file ; + skipda: Skip data block ; - slhdex: Search header of variables given by list and extract keywords ; . st2dim: Parse dimension string ; ! struct_rd: Read uio file and put data into anonymous structure ; . tab0: Create empty table structure ; + tabc: Change and modify table contents: rearrange lines. ; + tabm: Merge two tables in different ways ; + tabr: Read 1d array from 2d table array (all types) ; + tabw: Write 1d array into table (all types) ; uclose: Close file with special handling for conversion type ; uopen: Open file with special handling for conversion type ; vnanrm: Transform a string to give a correct name of a variable ; wf2rf: Produce from write format string corresponding read format string ; + wr: Writing scalar and array data of all types ; . wrfifo: Write file header ; wrhdme: Write header of variable, input: term table. ; wrhead: Write header of variable, input: line table. ; + wrlabl: Write label ; + wrtab: Write table of integer, real, and/or character data to file ;****************************************************************************** ; Include-Files uio_*.pro: ; filedefinc: ; uiocstinc: channel status information (common uio_chainf) ; uiocvlinc: convert type list of current machine (common uio_cvlist) ; uionaminc: names of types, keywords, identifiers; default formats ; (common uio_defnam) ; uiosizinc: length of strings, size of tables (trmtab, lintab) ; uiotabinc: empty table structure (common uio_taborg) ;******************************************************************************

Most of the routines are low-level ones and do not have to be worried about because they rarely will be used directly.

For accessing data in UIO format within IDL the initialization routine uio_init (see Sect.6.2.7.1) and the high-level reading routines (uio_struct_rd.pro, uio_dataset_rd.pro, and uio_datasetlist_rd.pro, see Sect.6.2.7.3) might suffice.

6.2.7.1 Initialization of UIO routines under IDL

The directory containing the IDL UIO routines should be added to the IDL variable !PATH. This could be done by a program segment in the startup procedure, like:

for example in the .bashrc file. Or one just copies or links the UIO IDL routines to a location in the standard IDL search path.

It is reasonable to include the UIO initialization in the startup procedure as e.g.:

IDL can handle the conversion types native, ieee_4, ieeele_4, ieee, idl, xdr (compare Tab. 6.2 in Sect 6.2.3.1). Here, ieee_4 is the default and should be used as a standard.

Attention: The IDL type ``long'' corresponds to the standard Fortran type ``integer''. The IDL types ``byte'' and ``integer'' are not known in standard Fortran and are therefore transformed to the IDL type ``long'' before writing (in the IDL routine uio_wr).

Be aware of: The parsing and interpretation of the entry headers can only be done by scalar operations which are comparatively slow in IDL.

6.2.7.2 Reading data with uio_data.pro

The IDL routine uio_data and the IDL function uio_d were the first set of ``high-level'' routines to read UIO data in IDL. They were useful for the easy reading of not too complex data files. By now, they are replaced by the routines uio_struct_rd and uio_dataset_rd (see see next Section and Sect 10).

6.2.7.3 Reading data with uio_dataset_rd.pro or uio_datasetlist_rd.pro

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.6.2.3.3, e.g.

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

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

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

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

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 e.g. modelident='_*', modelident='_??', modelident='_3?', or modelident='_{29,3[0-2]}'.