4.5.4 Sample Calls of Fortran UIO Routines

The needed modules have to be declared by a use statement like:

use uio_bulk_module

In the initial phase of the program the UIO routine package has to initialized by exactly one call of the uio_init routine with the name of the program as optional parameter:

call uio_init(progrm='uiotst')

The internal list of logical I/O unit numbers may be changed with calls of uio_chunit and uio_chconv.

A file can be opened for writing with

file='test.txt'
form='formatted'   ! or: 'unformatted'
conv='ieee_4'      ! or: 'native', 'crayxmp_8',...
call uio_openwr(ncout, file, form=form,conv=conv)

Header and data block are written together with one command as e.g. in:

call uio_wr(ncout, time,       'time', name='time',    unit='s'     )
call uio_wr(ncout, rho(1:10),  'rho',  name='density', unit='g/cm^3')

There are two different routines to close a file after reading or writing. A file opened for writing is closed by:

call uio_closwr(ncout)

To open a file for reading, only the file name has to specified. File form and conversion type are determined automatically:

file='test.txt'
call uio_openrd(ncin, file)

In contrast to the writing of an entry by one routine call the reading is performed in two separate sub-steps for the header and the data part. After the reading of the header e.g. with

use uio_siz_module
use uio_nam_module
...
integer                                 :: ntt
character*(let)                         :: termt(2,nttmx)
...
call uio_rdhd(ncin, termt,ntt)

the identifier, type, and dimension (if any) of the entry is contained in the character array termt with ntt entries and special actions may be taken: The data part may be skipped with

uio_skipda(ncin, termt,ntt)

or it can be read with:

call uio_rd(ncin, termt,ntt, time, ident)

If the entry is an array it may be necessary to allocate memory:

call uio_exkeyw(termt,ntt,  dimna,dimstr)
call uio_st2dim(dimstr, ilow, iup, ndim=ndim)
allocate(rho(ilow(1):iup(1)))
call uio_rd(ncin, termt,ntt, rho, ident, ilb=ilow(1:1))

Alternatively, it is possible to search in the file for a special entry or to search in a specially generated entry list with:

call uio_srhd(ncin, termt,ntt, type='real',ident='rho',outstr=outstr,ierr=ierr)

Additionally, the module uio_var_module makes it possible to read any entry into an UIO flexible variable, and the module uio_varfile_module allows the reading of a complete file into a special file structure of UIO flexible variables.

To close a file after reading use

uio_closrd(ncin)

There are several examples of programs with UIO routines like uio_var_test.f90, uio_varfile_test.f90, uiotst.f90, (uio_demo.f90) and - of course - CO5BOLD.