                      
                                 Bufr library 
                          ----------------------

Any comments either 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 bufr_000version.tar.gz

Content:
Makefile      					Makefile for 'everything'
build_library 					Script bilding library
install       					Install script
bufrdc        					Subdirectory containing BUFR encoding/decoding software
tables_tools    				Subdirectory containing tools to check and convert tables
bufrtables    					Subdirectory containing BUFR tables
pbio          					Subdirectory containing binary read/write routines
examples       					Subdirectory containing example programs for BUFR and tools
												for conversion between BUFR and CREX
config        					Subdirectory containing configuration files for make
options       					Subdirectory containing options files for make 

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

There are two possibilities for making the installation:

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

 ./build_library

or, compile the library yourself.
   To compile the library without the install script, follow the procedure
below.

   After library is built, Bufr tables 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.
**************************************************************



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 subdirectori  pbio

sources.sgimips



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

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

   ARCH indicates the machine architecture on which the BUFR 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 and sun4 systems,
CNAME=_gnu can be specified in order to compile with Gnu compilers.

   Values of CNAME which have been tested for different machine architectures
include:

decalpha - Compaq Fortran 90 compiler
         - the C++ compiler
hppa     - HP Fortran compiler
         - C compiler
linux    - The Portland Group Compiler Technology Fortran 90 compiler
         - 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

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



There are three ways of compilation:
-----------------------------------

1) Compile setting the ARCH variable just for this command

make ARCH=sgimips

   In this case CNAME and R64 are pre-defined. 

2) Compile setting the ARCH variable and choosing 64 bit reals just for this 
   command 

make ARCH=sgimips R64=R64

3) Compiling setting the CNAME=_gnu variable is valid on Linux and Sunos 
   which uses the Gnu compilers.
   For Windows(Cygwin) Gnu is pre-defined compiler.

make ARCH=linux CNAME=_gnu


   The library will be created in the working directory and be named libbufr.a 

   You can install bufr library on Windows only if you have Cygwin linux-like
environment for Windows and Gnu compilers.  

   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 put 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 variable
--------------------

IF YOU USE ./build_library SCRIPT YOU DON'T NEED TO SET ENVIRONMENTAL
	VARIABLES BELOW
   The location of BUFR tables should be specified by the environment variables
BUFR_TABLES. Put the specification of BUFR_TABLES in your startup files (.profile, ...)
to ensure you have access to the BUFR tables:
   Thus:

  BUFR_TABLES="choosen directory"/bufrtables/
  export BUFR_TABLES                                   (Bourne or Korn shell)

  setenv BUFR_TABLES "choosen directory"/bufrtables/   (C-shell)

   BUFR_TABLES should be defined to point to a directories containing
the BUFR tables. The initial location of these tables is in
"working directory"/bufrtables.


Changes to the interface
------------------------

A change has been made to the interface to the BUFR library. The argument
VALUES which is used by several BUFR library routines has been changed
to REAL*8. The example program includes this change.

Other significant changes
-------------------------

New version of BUFR tables B0000980601.TXT and D0000980601.TXT have
been included together with new tables B0000981101.TXT and
D0000981101.TXT.

   When compiling a example program, you need to specify where to find libbufr.a by
putting its full pathname in the makefile. The initial location of the library
is "working directory". An alternative is to put libbufr.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  -lbufr

 You can see an example of decoding a BUFR product using make in
examples directory. Invoke 'make' and start
an executable version of program bufr_example.F through:

   ./test.sh

   that temporary set env variable BUFR_TABLE
   and run

 ./bufr_example -i ../data/wmo_buoy.bufr

  for testing purpose before installation

   It can be re-run for some other file with other sort of observation.

   The decoding software is based on a example program (bufr_example.ex) which produces
a listing of the Bufr header records together with a few of the data values.

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

   >From here on any reference to SOFTWARE in file names should be interpreted
as the software you have received, i.e.  BUFR, 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, Bufr etc. and refers to a part of the
whole SOFTWARE set.


                   
Provided for UNIX systems.
--------------------------
                          
This README file.
The tar file bufr_000version.tar
   
Other UNIX systems.
------------------
                         
If you use a UNIX system other than those for which the software was prepared  
you should try to see if any of the existing configurations are suitable for 
your system.

if any problems are encountered the following 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 in a word and is it bigendian or littleendian ?
Some of the routines are dependent on the word size and which bit is the most 
significant. These dependencies are isolated in file gbyte.c e.g gbyte_alpha.c 
for a DEC Alpha system.

License
--------

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

