Emos library
                              --------------

   Any comments on the document or the software would be appreciated. 
   Please address comments to:

Software Services
ECMWF
Shinfield Park
Reading
Berkshire RG2 9AX
U.K.

Fax: +44 1734 869450

e-mail: software.services@ecmwf.int

The software is provided as a tar gzip file. This should be expanded using

tar -xfz emos_version.tar.gz

Content:
Makefile        Makefile for 'everything'
build_library   Script bilding library
install         Install script
gribex          Subdirectory containing GRIB encoding/decoding software
gribtables      Subdirectory containing GRIB tables
gribtemplates   Subdirectory containing Gribex templates
bufrdc          Subdirectory containing BUFR encoding/decoding software
bufrtables      Subdirectory containing BUFR tables
crexdc          Subdirectory containing CREX encoding/decoding software
crextables      Subdirectory containing CREX tables
land_sea_mask   Subdirectory containing land-sea mask
pbio            Subdirectory containing binary read/write routines
fft             Subdirectory containing Multiple FFT routines 
examples        Subdirectory containing example programs
config          Subdirectory containing configuration files for make
options         Subdirectory containing options files for make

**************************************************************

This is instruction how to build library and install:

Run the script bilding library and answer on a few questions:

 ./build_library

   After library is built, tables, land-sea mask and library should be
installed at appropriate place.

   It is recomended to do it by install script.

 ./install

   If you want to put library in /usr/local/lib directory,
you should run install script with root permission.

**************************************************************

It is strongly suggested to build the library using
shell script ./build_library  and install using ./install !!!

**************************************************************


Compilation options
-------------------

   Files are given for a variety of platforms defining the compilation options:
makefile configuration, compiler options and source file lists.

   Using SGI as an example, these files are:

1) In the working directory

   config.sgimips
   config.sgimipsR64
   options_sgimips

2) In subdirectories gribex and pbio

   sources.sgimips


Compiling the library
---------------------

   The correct configuration, options and source files can be selected using for 
make variables: ARCH, CNAME, A64 and R64.

   ARCH indicates the machine architecture on which the Emos library will be
installed. It may not necessarily have a pre-defined value. A list of possible
values could include: linux, windows, CRAY, FUJITSU, VPP5000, decalpha, hppa,
i686, ibm_power4, rs6000, sgimips and sun4.
   CNAME is used to name the compilers; it may or may not be pre-defined, depending
on the operational system you use. If you want to choose your own compilers, you
can define them in the appropriate 'config' file. For Linux CNAME=_gfortran can
be specified in order to compile with Gnu compilers gcc and gfortran.

decalpha - Compaq Fortran 90 compiler
         - the C++ compiler
hppa     - HP Fortran compiler
         - C compiler
linux    - The Portland Group Compiler Technology Fortran 90 compiler,
           pgf90 and pgcc
         - GNU project C, C++ Compiler, F77 compiler
rs6000   - XL Fortran for AIX
         - C for AIX Compiler, Version 5
sgimips  - MIPSpro F77 compiler
         - MIPS C compiler
sun4     - Forte[tm] Developer 7 Fortran 95 compiler
         - SunOS/BSD Compatibility Package C compiler

   A64 determines 32 or 64 bits machine.
   R64 determines the number of bits in the representation of real numbers.
The default is 32-bit. You can choose 64-bit setting R64=R64 in order to get
64-bit real numbers.


!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

If you decide to build the library using directly make, please NOTE that
you have to specify path for gribtables, bufrtables, crextables,
land_sea_mask, gribtemplates in appropriate

config/config.$ARCH$CNAME$R64

You should add -DTABLE_PATH=\'/your path\'/

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!



There are two ways of carrying out the compilation:
----------------------------------------------------

1) Compile setting the ARCH variable just for the command:

   make ARCH=sgimips

   In this case R64 is pre-defined. 

2) Compile setting the ARCH variable and choosing 64-bit reals;

   make ARCH=sgimips R64=R64

3) On Linux  compile setting CNAME=_gfortran to force the use of the Gnu
   compilers gfortran and gcc.

   make ARCH=linux CNAME=_gfortran

4) Same as 3) and added A64 if machine is 64 bits Linux

   make ARCH=linux CNAME=_gfortran A64=A64

   The library will be created in a working directory and be named libemos(R64).a.

   It is recommended that users should not change any routines in the source 
sub-directories because any changes would not be present in future ECMWF 
releases of this software.

   You can use other options for compilation. For example: selecting the working
directory; modifying the configuration files; changing the level of
optimisation; etc. The 'make' utility can be used repeatedly. It will only
cause the re-compilation of routines which have been modified since the
previous 'make'.


Environment variables
---------------------

IF YOU USE ./build_library SCRIPT YOU DON'T NEED TO SET ENVIRONMENTAL
VARIABLES BELOW.

  The location of tables and land-sea mask could be specified by the environment
variables. Put the specification of them in your startup files (.profile, ...)
to ensure you have access to the tables and land-sea
on future logins.

Bourne or Korn shell:

  ECMWF_LOCAL_TABLE_PATH="choosen directory"/gribtables/
  export ECMWF_LOCAL_TABLE_PATH

  LOCAL_DEFINITION_TEMPLATES="choosen directory"/gribtemplates/
  export LOCAL_DEFINITION_TEMPLATES

  BUFR_TABLES="choosen directory"/bufrtables/
  export BUFR_TABLES

  CREX_TABLES="choosen directory"/crextables/
  export CREX_TABLES

  MARS_LSM_PATH="choosen directory"/land_sea_mask/
  export MARS_LSM_PATH

  HIRLAM_LSM_PATH="choosen directory"/land_sea_mask/
  export HIRLAM_LSM_PATH


C-shell:

  setenv ECMWF_LOCAL_TABLE_PATH "choosen directory"/gribtables/
  setenv LOCAL_DEFINITION_TEMPLATES "choosen directory"/gribtemplates/
  setenv BUFR_TABLES "choosen directory"/bufrtables/
  setenv CREX_TABLES "choosen directory"/crextables/
  setenv MARS_LSM_PATH "choosen directory"/land_sea_mask/
  setenv HIRLAM_LSM_PATH "choosen directory"/land_sea_mask/

   The environment variable GRIBEX_DEBUG can be set to ON or OFF
to switch on or off the debug output from GRIBEX.

   The environment variable GRIBEX_CHECK can be set to ON or OFF
to switch on or off the checking of headers in GRIBEX.

   The environment variable JDCNDBG can be set to 1 in order to get
comperhensive output from INTERPOLATION routines

   The following variable can be set to "true" in order to create CREX massege
with check digit.

 USE_E=TRUE

	HIRLAM_LSM_PATH is place for LSM_GG_xxxx, reduced gaussian land-sea mask files,
which is used just for rotation of surface fields. LSM_GG_xxxx files supplied 
with package are just for LITTLE ENDIAN machines. 
   When compiling a program, you need to specify where to find libemos.a by
putting its full pathname in the makefile. The initial location of the library
is "working directory". An alternative is to put libemos.a in /usr/local/lib
(this may need system priviliges) which is conventionally used on UNIX-type
systems for holding libraries and should be defined in your environment PATH
variable.

   The library name follows the normal UNIX convention (it starts with lib and ends
in .a), so the library can be specified in the compile/link command using the
standard ld convention, for example:

        cc -o program program.c  -lemos
   You can see an examples of decoding a GRIB, BUFR, CREX product and interpolation
in examples/ directory.

cd examples

than choose bufr, crex, gribex, interpolation, fft directory.

 Invoke 'make' and start an executable version of program e.g. agrdemo.F through:

   ./test.sh

  In case of gribex example that will temporary set env variables
 ECMWF_LOCAL_TABLE_PATH and LOCAL_DEFINITION_TEMPLATES
   and run

  ./agrdemo -i ../../data/latlon.grib

  for testing purpose before installation

   where latlon.grib is a file containing GRIB fields on latitude/longitude
grids.

   It can be re-run for gaussian grids and spherical harmonic fields.

Terminology
-----------

   >From here on, any reference to SOFTWARE in file names should be interpreted
as the software you have received, i.e. GRIB, PBIO etc.

   The use of the word PLATFORM refers to the make of the computer for which the 
software is intended and substitutes for CRAY, sun etc.

   SUBPACKAGE could be any of pbio, gribex etc. and refers to a part of the
whole SOFTWARE set.


Provided for UNIX systems named above.
--------------------------------------

   This README file.
   The tar file emos_000version.tar (version is a 3-digit number).


Other UNIX systems.
-------------------

   If you use a UNIX system other than those for which the software was prepared,
you should experiment with the configurations provided to see if any are
suitable for your system.

   If any problems are encountered, the following points are worth considering:

Is your cc compiler ANSI?
The C code in this software is ANSI conformant.

Does your FORTRAN compiler need other switches?
Look at other programs compiled on your system.

Does your system need a ranlib command performed on the libraries?
Do "man ar" or "man ranlib".

How many bytes are there in a computer word. Is the platform big-endian or
little-endian? Some of routines are dependent on the word size and on which bit
in a computer word is the most significant. These dependencies may be resolved
by choosing one or other of the files gbyte.c or gbyte_alpha.c(for a
little-endian system).


License
--------

This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE.
See LICENSE and gpl-3.0.txt for details.