next up previous contents index
Next: 6.2.6 UNIX scripts Up: 6.2 UIO data format Previous: 6.2.4 Files & directories   Contents   Index


6.2.5 Fortran90 Files

The Fortran UIO package is a collection of Fortran90 modules and programs described in Table 6.5.

Table 6.5: UIO Fortran90 files
File   Contents
uio_base_module.f90   Collection of basic modules
uio_mac_module.F90   Machine-dependent routines for all machines
uio_bulk_module.f90   Main part of UIO routines
uio_filedef_module.f90   Standard file descriptors and labels
uio_table_module.f90   Table manipulation routines
uio_var_module.f90   Definition and handling of UIO flexible variable
uio_varfile_module.f90   Definition and handling of file structure of
    UIO flexible variables
uiocop.f90   Program to copy and transform UIO files
uiolok.f90   Program to look into UIO files
uioinf.f90   Program to give information about conversion types
uiotst.f90   Program to produce test UIO file

The file uio_base_module.f90 contains the basic set of modules (see Table 6.6).

Table 6.6: Contents of uio_base_module.f90
Module   Contents
uio_cst_module   Channel status information
uio_cvl_module   Convert type list of current machine
uio_inf_module   Information about environment
uio_nam_module   Definition of names
uio_siz_module   String length, table size
uio_base_module   Basic set of UIO-routines: string processing,
    header handling, I/O channel management

In older version of CO5BOLD, the files uio_mac*_module.f90 (Tab. 6.5) contained machine-dependent routines collected in the module uio_mac_module (see Tab. 6.7).

Table 6.7: Contents of uio_mac_module
Routine   Purpose
uio_getenv   Get information about environment
uio_mkcvls   Make list with possible conversion types
uio_uopen   Open file with special handling for conversion type
uio_uclose   Close file with special handling for conversion type

In the current version of CO5BOLD, there is only one file uio_mac_module.F90 - with a capital F90 - that can be changed during the compilation by preprocessor switches, see 4.4.2.

The main set of routines is contained in uio_bulk_module.f90 in the module uio_bulk_module. The three files uio_base_module.f90, uio_mac_module.F90, and uio_bulk_module.f90 comprise the standard set of UIO routines. Additionally, there exists a file uio_table_module.f90 with the single module uio_table_module which permits the I/O and manipulation of a certain table format (see the example in section 6.2.2).

The latest extension comes within the modules uio_var_module.f90 and uio_varfile_module.f90. The module uio_var_module.f90 contains a type definition for a variable (``uio flexible variable'') of general type (i.e. it may be a scalar integer value or a 1D character array or a 3D real array...) together with some routines for the basic handling of the variables (I/O in UIO format, construction and modification of variables...). The module uio_varfile_module.f90 contains a type definition for a file built of UIO flexible variables together with routines for the handling of these files. Use of UIO modules in Fortran90

To make the UIO routines available in a Fortran program the appropriate modules have to be specified in a USE statement.

At maximum five modules play a role: The uio_bulk_module contains the main part of the UIO routines (and also uses the relevant sub-modules). Instead of uio_bulk_module the module uio_table_module is used if the UIO table routines are needed. The modules uio_siz_module and uio_nam_module contain specifications about the size of some arrays and the length of strings, and the names of types and keywords, respectively. The module uio_filedef_module contains some definitions in addition to the basic UIO standard as e.g. the label names which delimit a data set (label dataset and label enddataset).

A typical case for the use of UIO modules is

use uio_bulk_module
use uio_siz_module
use uio_nam_module Compiling and Makefiles

For a certain platform, it was necessary to change the name of the module file with the machine-dependent routines (uio_mac*_module.f90) in a Makefile for the UIO routines. For this purpose the environment variable UIOMAC had to be set to the name of the appropriate routine (see Sect.3.1).

In the current version of CO5BOLD, there is only one file uio_mac_module.F90 - with a capital F90 - that can be changed during the compilation by preprocessor switches, see 4.4.2.

For CO5BOLD or the UIO Unix scripts, the respective configure script takes care of either of these steps. Many compilers generate module information files with suffixes like .M, .mod, or .kmo. To clean up information files with other suffixes, they have to be included in the cleaning step. Calling examples:

make UIO
make UIO "F90FLAGS=-g"
make clean
make cleanall
make remove
make removeall

A section of a typical Makefile using the UIO routines may be

# -- Compiler options --
# -- Libraries --
# -- Dependencies of exe-files on object files and libraries --
test.exe: test.o
        $(F90C) $(F90FLAGS) -o $@  

        $(UIOPATH)/f90/uio_base_module.o $(UIOPATH)/f90/$(UIOMAC).o  


test.o: $(UIOPATH)/f90/UIO test.f90
        $(F90C) -c $(F90FLAGS)  
# -- Dependencies on used modules --
        cd $UIOPATH/f90 ; make UIO "F90FLAGS=$F90FLAGS" Sample calls of Fortran UIO routines

Examples for routines with UIO input/output in CO5BOLD are tabinter_rdcoeff, tabinter_wrcoeff, rhd_box_RdData, rhd_box_WrData, rhd_datx_Write, and rhd_par_RdData. 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

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:

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)
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 uio_var_module makes it possible to read any entry into an UIO flexible variable, and the 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


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.

next up previous contents index
Next: 6.2.6 UNIX scripts Up: 6.2 UIO data format Previous: 6.2.4 Files & directories   Contents   Index