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:

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.