NCEP Home > NCO Home > Systems Integration Branch > Decoders > CREXLIB Table of Contents > Introduction
Introduction
Throughout the discussion of the CREXLIB software, it will be helpful
for the reader to be able to visualize a CREX message
as containing one or more CREX data subsets, each containing the data for a
single report from a particular observing site at a particular time and
location.
In turn, each data subset (i.e. report) will, in addition to time and location
information, typically contain environmental data values. A report for example
may contain tide gauge data or it may contain ozone soundings.
Finally, CREX messages themselves are typically stored in files
containing many other CREX messages of similar content. Therefore, if we were
to summarize in a top-down fashion, we would have:
"A CREX file contains one or more CREX messages, each containing one
or more CREX data subsets, each containing one or more CREX data values."
If nothing else, remembering this hierarchy will at least make the user
interface
to the CREXLIB software more intuitive, and for that alone it is worth
keeping in mind!
So, without further ado, let's dive in!
The CREXLIB software contains over 20 routines. A typical user needs only to be
familiar with the calling arguments in the main routine, CX_DCOD.
The rest are lower-level routines that the the software uses to accomplish
various underlying tasks and which can therefore be safely treated as a
"black box" from a user perspective. Do note, however, that the software is
written in FORTRAN 77 and is intended to be used as a library rather than as
a "stand-alone" program; therefore, the user must possess at least a
rudimentary knowledge of FORTRAN 77 in order to be able to fashion an
application program which calls the CREXLIB routine CX_DCOD. An example
application program is provided within the documentation to illustrate the
procedure for using the CREXLIB library.
The purpose of the routines in the CREXLIB is to decode the data in a CREX
message. This assumes then that a user of the CREXLIB has written a program
which gets a CREX message and passes that message to the CREXLIB routines.
The user needs only to call the main CREXLIB subroutine CX_DCOD and pass to
it the following arguments.
CALL CX_DCOD ( lutblb, lutbld, mxndesc, mxrpt,
mxrptsz, mxdatv, lenb, bulltn,
ctbla, ctblds, ndesc, datadesc,
nmrpts, nmdesc, expdesc, lenrpts,
rawrpt, nmdatval, dataval, iret )
Input arguments:
LUTBLB INTEGER CREX Table B logical unit number
LUTBLD INTEGER CREX Table D logical unit number
MXNDESC INTEGER Maximum number of descriptors expected
in Section 1 of CREX message
MXRPT INTEGER Maximum number of reports expected
in message
MXRPTSZ INTEGER Maximum report size expected
MXDATV REAL Maximum number of data values expected
in message
LENB INTEGER Length in bytes of bulletin containing
the CREX message
BULLTN CHARACTER Array holding the CREX bulletin data
The user must provide the CREX Tables B and D, which will be either the
current WMO CREX tables or a subset of them. It is assumed that the user
is familiar with the particular CREX message to be decoded. This implies
that the user will be able to define those arguments above that require
maximum values in order to enable realistic sizing of the arrays used
in the CREXLIB routines.
Output arguments:
CTBLA CHARACTER 3-digit CREX Table A reference
CTBLDS CHARACTER CREX table descriptor (Ttteevv as described
in the WMO FM 95 CREX code form)
NDESC INTEGER Number of data descriptors in Section 1
of CREX message
DATADESC CHARACTER Array dimensioned (MXNDESC) containing the
list of descriptors in Section 1
NMRPTS INTEGER Number of reports in CREX message
NMDESC INTEGER Number of descriptors in array EXPDESC
EXPDESC CHARACTER Array dimensioned (MXDATV) containing the
list of the expanded Section 1 descriptors.
The expansion consists of replacing the
sequence and non-delayed replication
descriptors with the list they correspond
to. The final list will be close to a
one-to-one correspondence with the data
values in Section 2.
LENRPTS INTEGER Array dimensioned (NMRPTS) containing the
length of each subset in CREX message
RAWRPT CHARACTER Array doubly dimensioned (MXRPT,MXRPTSZ) to
hold the subsets in CREX message
NMDATVAL INTEGER Number of data values in Section 2 subset
DATAVAL REAL Array doubly dimensioned (MXRPT,MXDATV) to hold
the Section 2 decoded values
IRET INTEGER Return code
0 = Normal return; 1 = Problems
These output arguments contain the decoded data. The user will need to
familiarize himself or herself with how the data is layed out in the arrays.
The EXPDESC array contains the list of the descriptors which will match the
layout of the data in a Section 2 subset. This descriptor list is used for
each of the Section 2 subsets. The array DATAVAL holds all the Section 2
subset data. Each subset data value is stored in an DATAVAL array location
and each subset takes NMDATVAL locations in DATAVAL, so the user will be able
to get the data values for all or a particular subset.
Every CREX message that is presented to the CREXLIB software must have CREX tables
associated with it, and these tables may be defined within a
separate ASCII text file (see Description and Format of CREX Tables for more info.)
Note that LUTBLB and LUTBLD
are logical unit numbers; therefore, the user within his or her application
program must have already associated these logical unit numbers with the actual
Tables B and D.
|