1. Introduction
This document describes the library of programs that work with BURP (Binary Universal Report Protocol) format files. The set of functions and subroutines are written in FORTRAN or in C. The general rule is if the name of the module in FORTRAN is like this "MRBTBL", then in C it would be like this "c_mrbtbl". Note the uppercase used in FORTRAN and the lowercase used in C. The present document describes the new method proposed for storing meteorological data in one point. Here you will find the description of the BURP data storage format as well as the total set of subroutines that works with and creates BURP files. This software complements the software for "RPN standard files". The BURP files have a structure of "several variables and/or values in one point" as opposed to a structure of "one variable having values in many different points" in the RPN standard files. This is the difference between a meteorological report and a meteorological field. These files are intended among other things to replace the old "derivate" files, used for producing the analysis and plotting the observations from stations.
2. Structure
The base unit in these files is the
"meteorological report" which is a set of blocks of data at one given
point. A segment is a set of these meteorological "reports", and in
turn, a set of these segments make a file. A report has a header
containing general information (geographical location, type of report,
date of data received, etc.) and a set of tables representing
meteorological variables (ie: temperature, pressure, humidity,...) Each
of these tables is associated to a list indicating the variables who
contain a mini block of information (number of variables, number of bits
per value, number of values per variable, identification of the block).
A table can contain several values associated to one same variable (ie:
"upper air sounding").
The representation of values and variable
names are borrowed from the "BUFR" standard of WMO. The whole 16 bits
are used to represent the type of variable and all the values are
reduced to whole unsigned numbers. The list of codes, scale factors and
reference values for the different variables can be found in the
document FM 94 BUFR. Look in the Appendix for what is not covered in
this document.
The software is at two levels. In the first
level, the subroutines allow us to manipulate the interior of a report
while in the second level, the subroutines allow us to manipulate the
files themselves.
In creating a report, the user provides an array where the first element contains the length of this array.
in FORTRAN:
INTEGER BUF(500)
BUF(1) = 500
in C:
int buf[500]
buf[0] = 500
Make sure this array is long enough
for holding all the blocks which makes a report plus a dozen of words
used to contain the supplementary control information. One can obtain
the length of an already existing report by using the functions MRFPRM
and MRMXL. The length returned by these functions plus the dozen of
words mentioned above gives the dimension of the array BUF. In general, a
length of 1000 words should be sufficient to hold a report. (For the
exact formula to calculate the length of BUF required to hold a report
that one wants to create, refer to Appendix B). It is the BUF array that
we pass to varying subroutines which make up the software package for
carrying out the diverse operations of reading/writing of reports,
extraction/creation/destruction of tables, etc.
The BURP files are a type of XDF file. It is
therefore possible to recuperate the space occupied by deleted reports
and merge several files into one using the RPN utility REFLEX. To obtain
all the information about XDF files or the utilities REFLEX, look in
the section RPN Utilities at the WEB site for RPN Documentation:
3. STORAGE FORMAT
3.1 DESCRIPTION OF A FILE
|
|
|
|
|
|
A "BURP" file is made of a header and
one or several segments containing reports. See the detailed description
of the file header in the document describing the XDF files.
3.2 DESCRIPTION OF A SEGMENT
|
|
|
|
|
|
Several reports are grouped in the same segment up until a limit of 256.
3.3 DESCRIPTION OF THE DIRECTORY OF A SEGMENT
|
|
|
|
|
|
See the detailed description of the directory header in the document describing the XDF files.
3.4 DESCRIPTION OF A REPORT
|
|
|
|
|
|
Each report is made of a header and n number of blocks of data.
3.5 DESCRIPTION OF A REPORT HEADER
|
|
|
|
|
|
See the detailed description of the header from the report and the block header from Appendix A.
3.6 DESCRIPTION OF A BLOCK
|
|
|
4. FIRST LEVEL SUBROUTINES
This set of FORTRAN and C functions
allow us to manipulate the elements inside a report. Certain functions
are used to manipulate the header of a report while others are used for
manipulating the blocks of data in a report. One can extract, delete,
replace or add a block of data. Each block of data is made of a block
header, a list of variables, and an array of values in one, two, or
three dimensions. All are defined in integer values.
4.1 CALLING SEQUENCE
In the FORTRAN description, an argument in UPPERCASE is for output , and an argument in lowercase is for input.
In the C description, all the arguments are in lowercase and there is
an '&' in front of the output argument (except in the case of arrays
where it is necessary to pass an address).
ISTAT=MRBADD(BUF,BKNO,nele,nval,nt,bfam,bdesc,btyp,nbit,BIT0,datyp, lstele,tblval)
istat=c_mrbadd(buf,&bkno,nele,nval,nt,bfam,bdesc,btyp,nbit,&bit0,datyp, lstele,tblval) To add a block of data at the end of a report.
ISTAT=MRBDEL(BUF,bkno)
istat=c_mrbdel(buf,bkno)
To delete a block of data (block bkno) and recuperate the space that it had occupied.
ISTAT=MRBHDR(buf,TEMPS,FLGS,STNID,IDTP,LATI,LONG,DX,DY,ELEV,DRND,DATE, OARS,RUNN,NBLK,SUP,nsup,XAUX,nxaux)
istat=c_mrbhdr(buf,&temps,&flgs,&stnid,&idtp,&lati,&long,&dx,&dy,&elev,
&drnd,&date,&oars,&runn,&nblk,sup,nsup,xaux,nxaux)
To get the parameters from the header of a report.
ISTAT=MRBINI(iun,BUF,temps,flgs,stnid,idtp,lati,long,dx,dy,elev,drnd, date,oars,runn,sup,nsup,xaux,nxaux)
istat=c_mrbini(iun,buf,temps,flgs,stnid,idtp,lati,long,dx,dy,elev,drnd, date,oars,runn,sup,nsup,xaux,nxaux)
To initialize the header of a report. It is
only after this that we can add blocks of data to this report. MRBINI
must be the first subroutine called to create a report.
ISTAT=MRBLEN(buf,LBITS,LEFT)
istat=c_mrblen(buf,&lbits,&left)
To find the number of bits (LBITS)used in the array BUF as well as the number of bits that are left free (LEFT).
BKNO=MRBLOC(buf,bfam,bdesc,btyp,blk0)
bkno=c_mrbloc(buf,bfam,bdesc,btyp,blk0)
To find the position of the first block of data of type "bfam,bdesc,btyp" which follows the block "blk0".
We set "blk0 = 0" if we want to start in the first block. If the value
of one of the keys (bfam,bdesc,btyp) is -1, then that key will not be
used during the search.
ISTAT=MRBPRM(buf,bkno,NELE,NVAL,NT,BFAM,BDESC,BTYP,NBIT,BIT0,DATYP)
istat=c_mrbprm(buf,bkno,&nele,&nval,&nt,&bfam,&bdesc,&btyp,&nbit, &bit0,&datyp)
To extract the descriptor parameters from the block "bkno" of data.
ISTAT=MRBREP(BUF,bkno,tblval)
istat=c_mrbrep(buf,bkno,tblval)
To replace a block of data by another that contains the same variables and dimensions.
ISTAT=MRBTYP(BKNAT,BKTYP,BKSTP,btyp)
ISTAT=MRBTYP(bknat,bktyp,bkstp,BTYP)
istat=c_mrbtyp(bknat,bktyp,bkstp,btyp)
If btyp = -1, then a search key will be
derived from bknat,bktyp and bkstp and placed in btyp; the function will
also return the value of btyp itself.
If btyp > 0, then it will decode the "btyp" and return values in bknat,bktyp,bkstp; the function will return 0.
ISTAT=MRBUPD(iun,BUF,temps,flgs,stnid,idtp,lati,long,dx,dy,elev,drnd, date,oars,runn,sup,nsup,xaux,nxaux)
istat=c_mrbupd(iun,buf,temps,flgs,stnid,idtp,lati,long,dx,dy,elev,drnd, date,oars,runn,sup,nsup,xaux,nxaux)
To update the header of a report. If the
value of a parameter is -1 ('*' for STNID), it will not have an
up-to-date value of the parameter. If NSUP = 0, SUP is ignored. If NXAUX
= 0, XAUX is ignored.
ISTAT=MRBXTR(buf,bkno,LSTELE,TBLVAL)
istat=c_mrbxtr(buf,bkno,lstele,tblval)
To extract a block of data (block bkno) from a report.
4.2 ARGUMENTS
1uppercase for FORTRAN, lowercase for C
| Argument | Type1 | Description |
| BDESC | INTEGER int |
Block descriptor. (0-2047) |
| BFAM | INTEGER int |
Family block descriptor. (0-31) |
| BIT0 | INTEGER int |
Number of the first right bit from block, calculated automatically by the software. (0-->2**26-1) (always a multiple of 64 minus 1) |
| BKNAT | INTEGER int |
kind component of Block type(BTYP). |
| BKNO | INTEGER int |
Block number. (1-65535) |
| BKSTP | INTEGER int |
Sub data-type component of Block type(BTYP). |
| BKTYP | INTEGER int |
Data-type component of Block type(BTYP). |
| BLK0 | INTEGER int |
Block number. (1-65535) |
| BTYP | INTEGER int |
Block type(made from 3 components:BKNAT,BKTYP,BKSTP). (0-2047) |
| BUF | INTEGER (*) int [] |
Array used to store a
report. This array must be large enough to contain the whole report plus
a dozen of words. The first element in the array must contain the
length used in the array. (in words) eg. INTEGER BUF(300) BUF(1) = 300 This is to allow the software to prevent accidental overflows. |
| DATE | INTEGER int |
Valid synoptic date (YYMMDD) |
| DATYP | INTEGER int |
Data type (for packing/unpacking). 0 = string of bits (bit string) 2 = unsigned integers 3 = characters (NBIT must be equal to 8) 4 = signed integers 5 = uppercase characters (the lowercase characters will be converted to uppercase during the read. (NBIT must be equal to 8) 6 = real*4 (ie: 32bits) 7 = real*8 (ie: 64bits) 8 = complex*4 (ie: 2 times 32bits) 9 = complex*8 (ie: 2 times 64bits) Note: Type 3 and 5 are processed like strings of bits thus, the user should do the data compression himself. |
| DX | INTEGER int |
Width of a box for regrouped data (delta lon) in tenth of degrees. |
| DY | INTEGER int |
Height of a box for regrouped data (delta lat) in tenth of degrees. |
| DRND | INTEGER int |
Reception delay:
difference between the reception time at CMC and the time of observation
(TEMPS). For the regrouped data, DRND indicates the amount of data. DRND = 0 in other cases. |
| ELEV | INTEGER int |
Station altitude in metres + 400. (0 to 8191) |
| FLGS | INTEGER int |
Global markers (24 bits) See Appendix A. |
| IDTP | INTEGER int |
Type of report |
| ISTAT | INTEGER int |
Status indicator, see list of codes in Appendix C. |
| IUN | INTEGER int |
Unit number for file. |
| LATI | INTEGER int |
Latitude in hundredths of a degree with respect to the south pole. (0 to 1800) (100+(latitude+90)) of a station or the lower left corner of a box. |
| LBITS | INTEGER int |
Number of bits used to code the report in the array BUF. |
| LEFT | INTEGER int |
Number of free bits left in the BUF array that was used to code the report. This allows you to know if there is enough space to place the next block of data. |
| LSTELE | INTEGER (NELE) int [nele] |
List of element names in the report in numeric BUFR codes. See the code representation in the FM 94 BUFR manual. |
| LONG | INTEGER int |
Longitude in hundredths of a degree (0 to 36000) of a station or lower left corner of a box. |
| NBIT | INTEGER int |
Number of bits per value. When we add a block, we should insure that the number of bits specified is large enough to represent the biggest value contained in the array of values in TBLVAL. The maximum number of bits is 32. |
| NBLK | INTEGER int |
Number of blocks contained in the report. |
| NELE | INTEGER int |
Number of meteorological elements in a block. 1st dimension of the array TBLVAL(block). (0-127) |
| NVAL | INTEGER int |
Number of values per element. 2nd dimension of TBLVAL(block). (0-255) |
| NT | INTEGER int |
Number of groups of NELE by NVAL values in a block. 3rd dimension of TBLVAL(block). (ie: time-series). (0- 255) |
| NXAUX | INTEGER int |
Dimension of array XAUX. 0 indicates that XAUX is not used. |
| NSUP | INTEGER int |
Dimension of array SUP. 0 indicates that SUP is not used. |
| OARS | INTEGER int |
Reserved for the Objective Analysis. (0-->65535) |
| RUNN | INTEGER int |
Operational pass identification. |
| STNID | CHARACTER*9 char [9] |
Station identification. If it is a surface station, STNID = WMO number. The name is aligned at left and filled with spaces. In the case of regrouped data, STNID contains blanks. |
| SUP | INTEGER (NSUP) int [nsup] |
Array to contain supplementary primary keys. (reserved for future expansion). |
| TEMPS | INTEGER int |
Hour of observation (HHMM) |
| TBLVAL | INTEGER(NELE,NVAL,NT) int [nele,nval,nt] |
Array for data (block). |
| XAUX | INTEGER (NXAUX) int [nxaux] |
Array to contain supplementary auxiliary keys. (reserved for future expansion). |
5. SECOND LEVEL SUBROUTINES
This set of FORTRAN and C functions is
for manipulating the reports as a whole. You can open or close a file
of reports, read or write a report, obtain or modify the descriptor
parameters of a report, and control the position or get the status of a
file.
5.1 CALLING SEQUENCE
In the FORTRAN description, an argument in UPPERCASE is for output , and an argument in lowercase is for input.
In the C description, all the arguments are in lowercase and there is
an '&' in front of the output arguments (except in the case of
arrays where it is necessary to pass an address).
ISTAT=MRFCLS(iun)
istat=c_mrfcls(iun)
To close a file of reports. Forgetting to close a file after using it could damage the file enough to be useless afterwards.
ISTAT=MRFDEL(handle)
istat=c_mrfdel(handle)
To delete the report pointed by "handle".
ISTAT=MRFGET(handle,BUF)
istat=c_mrfget(handle,buf)
To go get the contents of the report pointed by "handle" and put it in BUF.
ISTAT=MRFGOC(optnom,OPVALC)
istat=c_mrfgoc(optnom,opvalc)
To obtain the value of an option stored in character format.
ISTAT=MRFGOR(optnom,OPVALR)
istat=c_mrfgor(optnom,&opvalr)
To obtain the value of an option stored in real format.
HANDLE=MRFLOC(iun,handle,stnid,idtyp,lati,long,date,temps,sup,nsup)
handle=c_mrfloc(iun,handle,stnid,idtyp,lati,long,date,temps,sup,nsup)
To locate the pointer (HANDLE) of the report
that matches the STNID, IDTYP, LATI, LONG, DATE, TEMPS parameters and
the contents of array SUP. The search will start at the beginning if
"handle" is equal to 0 otherwise, the search will start on the report
that follows the report pointed to by "handle". If an element of STNID
is equal to an asterik ('*'), this element will be considered like a
"wildcard" and will be ignored during the search. It is the same for
IDTYP, LATI, LONG, DATE, TEMPS and SUP if their values are -1. Note that
only the "hour" portion of the argument TEMPS is used during the
search.
LNMX =MRFMXL(iun)
lnmx =c_mrfmxl(iun)
Function returning the length of the longest report in the file IUN.
NBENR=MRFNBR(iun)
nbenr=c_mrfnbr(iun)
Function returning the number of active
reports contained in the file IUN. The file can be opened or closed. If
the file is open, MRFNBR will leave it open and if the file is closed,
it will leave it closed.
ISTAT=MRFOPC(optnom,opvalc)
istat=c_mrfopc(optnom,opvalc)
Function used to initialize an option that is in CHARACTER format.
NBENR=MRFOPN(iun,mode)
nbenr=c_mrfopn(iun,mode)
To open a file of reports. It returns the number of active reports in the file.
ISTAT=MRFOPR(optnom,opvalr)
istat=c_mrfopr(optnom,opvalr)
Fucntion used to initialize an option that is in REAL format.
ISTAT=MRFPRM(handle,STNID,IDTYP,LATI,LONG,DX,DY,DATE,TEMPS,FLGS, SUP,nsup,LNGR)
istat=c_mrfprm(handle,&stnid,&idtyp,&lati,&long,&dx,&dy,&date, &temps,&flgs,sup,nsup,&lngr)
To go get the main parameters from the report pointed to by HANDLE.
ISTAT=MRFPUT(iun,handle,buf)
istat=c_mrfput(iun,handle,buf)
To write a report. If HANDLE is not NUL, we
overwrite the report pointed by ABS(HANDLE). If HANDLE = 0, we write a
new report at the end of the file.
ISTAT=MRFVOI(iun)
istat=c_mrfvoi(iun)
To list on unit 6 (standard output), the parameter descriptors from reports contained in the file IUN.
5.2 ARGUMENTS
1uppercase for FORTRAN, lowercase for C
| Argument | Type1 | Description |
| IUN | INTEGER int |
Unit number of file |
| BUF | INTEGER (*) int [] |
Array containing the report |
| DATE | INTEGER int |
Valid synoptic date. (YYMMDD) |
| DX | INTEGER int |
Width of a box for regrouped data (delta long) in tenth of degrees. |
| DY | INTEGER int |
Height of a box for regrouped data (delta lat) in tenth of degrees |
| FLGS | INTEGER int |
Global Markers (24 bits) See Appendix A. |
| HANDLE | INTEGER int |
Pointer to a report, generally obtained by a call to MRFLOC. |
| IDTYP | INTEGER int |
Type of report (Code type) |
| ISTAT | INTEGER int |
Error indicator: 0=OK, <0=error, >0=information. |
| LATI | INTEGER int |
Latitude in hundredth of degrees with respect to the south pole (0-18000) of a station or the left lower corner of a box. |
| LNGR | INTEGER int |
Length of a report (in words for the host machine). |
| LNMX | INTEGER int |
Length of the longest report contained in a file. This length is expressed in words for the host machine. |
| LONG | INTEGER int |
Longitude in hundredth of degrees (0-35999) of a station or the lower left corner of a box. |
| MODE | CHARACTER *(*) char [] |
'READ' : to open for read only 'CREATE' : to open a new file 'APPEND' : to open for append |
| NBENR | INTEGER int |
Number of active reports contained in a file. |
| NSUP | INTEGER int |
Number of supplementary keys (ignored in the version 1). Set to zero for now. |
| OPTNOM | CHARACTER *(*) char [] |
Name of an option modifiable by the user. Options in CHARACTER format: 'ERRTOLR' - level of tolerance for errors. Options in REAL format: 'MISSING' - value for missing data. |
| OPVALC | CHARACTER *(*) char [] |
Values for option OPTNOM='ERRTOLR': OPVALC can take the following values: 'TRIVIAL' 'INFORMATIF' 'WARNING' 'ERROR' 'FATAL' 'SYSTEM' |
| OPVALR | REAL float |
Values for option OPTNOM='MISSING': OPVALR can take the following values:???? |
| STNID | CHARACTER *(9) char [9] |
Report identification (name of the station). In the case of regrouped data, STNID contains nothing. |
| SUP | INTEGER *(NSUP) int [nsup] |
Supplementary keys (for expansion) |
| TEMPS | INTEGER int |
Time of observation (HHMM). Only the hour portion is used during a search. |
6. AUXILIARY SUBROUTINES
The first function below is used to convert integer values (BUFR format) to variables of real values (CMC units) while the other functions are used to code or decode the name of an element or a list of element names. When a list of elements is provided (LSTELE(NELE)) or LISTE(NELE) to different modules of BURP, each element of the list must have been coded in a way to be able to hold a total of 16 bits. The conversion of the data values (MRBCVT) uses a pre-defined conversion table(array). The user can add a user-defined list of elements (TBLUSR) to this conversion table(array)
6.1 CALLING SEQUENCES
An argument in uppercase is an output argument while an argument in lowercase is an input argument. In C, the output arguments are preceded by an ampersand '&', except for the arrays, which are passed by an address.
ISTAT=MRBCVT(liste,TBLVAL,RVAL,nele,nval,nt,mode)
istat=c_mrbcvt(liste,tblval,rval,nele,nval,nt,mode)
Conversion of values from RVAL (real) to
TBLVAL (integer) or the inverse depending on the MODE. If MODE=0,
convert from TBLVAL to RVAL and if MODE=1, convert from RVAL to TBLVAL.
When we are dealing with variables described by a code instead of a
value (eg: present time, type of cloud), we don't do any conversion and
the value stays in the original input array. A missing data is indicated
by putting all the bits ON of the corresponding element in the array
TBLVAL while for the RVAL array, we insert the attributed value to the
option 'MISSING'.
ISTAT=MRBCOL(dliste,LISTE,nele)
istat=c_mrbcol(dliste,liste,nele)
Conversion of uncoded element names (6 digit
decimal BUFR format) contained in DLISTE to a code format where each
element name uses 16 bits. The coded (CMC format) elements are returned
in the array LISTE.
ISTAT=MRBDCL(liste,DLISTE,nele)
istat=c_mrbdcl(liste,dliste,nele)
To convert a list of of coded (CMC) element
names in array LISTE into 6 digit decimal BUFR format. The "decoded"
elements are returned in the array DLISTE.
ELEM = MRBCOV(delem)
ELEM = c_mrbcov(delem)
To convert a 6-digit decimal (BUFR) format element name (DELEM) into a 16 bit coded (CMC) format.
DELEM = MRBDCV(elem)
DELEM = c_mrbdcv(elem)
To convert a 16-bit coded (CMC) format element name (ELEM) into a 6-digit decimal BUFR format element name.
ISTAT=MRBSCT(tblusr,neleusr)
istat=c_mrbsct(tblusr,neleusr)
To initialize and add a user-defined array of
variables (TBLUSR) for conversion (RVAL to TBLVAL or vice versa) to the
conversion array used by MRBCVT. The uncoded names of elements defined
by the user should limit the values between 63000 and 63255 inclusively
and must be in coded (CMC) form before the call to MRBSCT.
6.2 ARGUMENTS
1uppercase for FORTRAN, lowercase for C
| Argument | Type1 | Description |
| DELEM | INTEGER int |
Element name in 6-digit decimal BUFR format (uncoded) |
| DLISTE | INTEGER (NELE) int [nele] |
List of element names in 6-digit decimal (BUFR) format (uncoded). |
| ELEM | INTEGER int |
Element name in 16 bit CMC format (coded). |
| ISTAT | INTEGER int |
Error code. See Appendix C |
| LISTE | INTEGER (NELE) int [nele] |
List of element names in 16 bit CMC format. See FM 94 BUFR + local supplement for code representation. |
| MODE | INTEGER int |
MODE = 0, TBLVAL(BUFR code) to RVAL(CMC units) MODE = 1, RVAL(CMC units) to TBLVAL(BUFR code) |
| NELE | INTEGER int |
Number of elements. |
| NELEUSR | INTEGER int |
Number of elements that the user wants to add to the conversion array. It is the second dimension of the array TBLUSR |
| NVAL | INTEGER int |
Amount of data per element. (0-255) |
| NT | INTEGER int |
Number of groups of NELE x NVAL values. 3rd dimension of the arrays RVAL and TBLVAL. |
| RVAL | REAL (NELE,NVAL,NT) float [nele,nval,nt] |
Data field in real values (CMC). |
| TBLVAL | INTEGER (NELE,NVAL,NT) int [nele,nval,nt] |
Data field in integer format (BUFR). |
| TBLUSR | INTEGER (3,NELEUSR) int [3,NELEUSR] |
Conversion table defined by user where: TBLUSR(1,i) - "code" name of element to be converted TBLUSR(2,i) - scale (ECHELLE) for the conversion TBLUSR(3,i) - bias (BIAIS) for the conversion For converting a real value to an integer, MRBCVT performs this operation: RVAL(i,j,k) =FLOAT(TBLVAL(i,j,k) + BIAIS) /10**ECHELLE |
DESCRIPTION AND POSITION OF DIFFERENT GLOBAL MARKERS in FLGS
| Bits | Description (marqueurs) |
| 0 | assembled stations |
| 1 | surface wind used |
| 2 | message unreliable (p/t) |
| 3 | incorrect coordinates |
| 4 | message corrected |
| 5 | message amended |
| 6 | station rejected by AO |
| 7 | station on black list |
| 8 | station to evaluate |
| 9 | superobservation |
| 10 | data observed |
| 11 | data derived |
| 12 | residues |
| 13 | verifications |
| 14 | TEMP, part RADAT |
| 15 | TEMP, part A |
| 16 | TEMP, part B |
| 17 | TEMP, part C |
| 18 | TEMP, part D |
| 19 | reserved |
| 20 | reserved |
| 21 | reserved |
| 22 | reserved |
| 23 | reserved |
CALCULATION OF THE MINIMUM LENGTH OF BUF
The length of BUF required to hold a report that one wants to create is calculated as follows:
Length of any block(I) of data:
LBLOC(I) = ( 128 + M64((NELE-3)*16) + M64(NELE*NVAL*NT*NBIT) )
Length of BUF to insert N number of blocks:
LONGUEUR =
where
LONGUEUR: length of BUF (in words) to hold the report
BITMOT: number of bits in a host machine word
M64(A): is defined as being the first number of bits larger or equal to A who is a multiple of 64. M64(A)=INT((A+63)/64)*64
For example: M(160) = INT((160+63)/64)*64 = 192
NELE, NVAL, NT et NBIT are defined in the text.
LIST OF ERROR CODES
In case of error, all the functions
used for BURP and XDF files return a message indicating the level of
severity to the calling program as it encounters the error. With the
function MRFOPC, the user can control the error level of severity to end
the program. Also, the BURP and XDF functions take a value greater or
equal to zero when there is no error (for example, to HANDLE) and a code
smaller than zero when there is an error. All the error messages have
the following general format:
***SEVERITE: MODULE nom_du_module message_explicatif
(***SEVERE: MODULE name of module explicit message)
for example:
***TRIVIALE: MODULE MRBADD POUR DATYP = 3 OU 5, METTRE NBIT EGAL À 8
(***TRIVIAL: MODULE MRBADD FOR DATYP = 3 OR 5, SET NBIT EQUAL TO 8)
Here is a list of different types of errors and the value returned in ISTAT on return of a function:
| NAME | DESCRIPTION OF ERROR | ISTAT |
| TRIVIA | Trivial Error | 1 |
| INFORM | Informative messages for the user | 2 |
| WARNIN | Warning Error | 3 |
| ERROR | Utmost Important Error | 4 |
| ERFATAL | Errors that the user should know | 5 |
| SYSTEM | Overflow error | 6 |
| KAPUT | Intolerable error, program crashed | 7 |
| EREDAT | Invalid Datyp | 16 |
| ERFRAP | File is not a report file | 30 |
| ERFMOD | Error in opening. Only READ, CREATE and APPEND are allowed. | 31 |
| ERCLEF | Too many supplementary keys | 32 |
| ERBNUM | Block number invalid | 33 |
| EROPTN | Option name unknown | 34 |
| ERBTAB | FATAL error related to TABLEBURP | 35 |
| ERBDOM | TRIVIAL error related TABLEBURP | 36 |
| ERELEM | Invalid element name | 37 |
| ERBTYP | Invalid BTP (smaller than zero) | 38 |
| ERRCELL | Incorrect NCELL dimension | 39 |
| ERNPRM | Incorrect TBLPRM dimension | 40 |
| ERCMPR | Value too big for 32 bits and DATYP=2 | 41 |
| NONOFTB | File created with non-official TABLEBURP | 42 |
| EREBDSC | Bad initialization of BDESC | 43 |
| EREIVC | Element code invalid for DATYP=(7 to 9) | 44 |
APPENDIX - D
EXAMPLES OF USE
PROGRAM BURPEX
INTEGER FNOM,MRFOPN,MRFLOC,MRFGET,MRFPUT,MRFCLS
INTEGER MRBLOC,MRBXTR,MRBHDR,MRBINI,MRBPRM,MRBADD
INTEGER BUF1(1000),BUF2(1000), HANDLE,ISTAT,NOMBRE
INTEGER TEMPS,DATE,OARS,RUNN
INTEGER IDTYP,LATI,LONG,DX,DY,ELEV,DRND,NBLOCS,BLKNO
INTEGER TBLVAL(10,100),LSTELE(10),NELEM,NVAL,NT
INTEGER IBLOC, BFAM,BDESC,BTYP,NBIT,BIT0,DATYP
CHARACTER*9 STNID
INTEGER SUP,XAUX
BUF1(1) = 1000
BUF2(1) = 1000
IER = FNOM(10,'BURPF10','RND',0)
IF(IER .NE. 0) THEN
PRINT *,'ERROR TO OPEN BURPF10'
STOP
ENDIF
IER = FNOM(20,'BURPF20','RND',0)
IF(IER .NE. 0) THEN
PRINT *,'ERROR TO OPEN BURPF20'
STOP
ENDIF
*
* OPENING FILE ON UNIT 10 FOR READ
*
NOMBRE = MRFOPN(10,'READ')
*
* OPENING NEW FILE ON UNIT 20 FOR WRITE
*
NOMBRE = MRFOPN(20,'CREATE')
*
* TO GET ALL THE REPORTS FOR THE STATION01 FOR JUNE 12, 12Z
* AND READ THEM
HANDLE = 0
HANDLE = MRFLOC(10,HANDLE,'STATION01',-1,-1,-1,120691,
1 1200,SUP,0)
1000 IF(HANDLE .GT. 0) THEN
ISTAT = MRFGET(HANDLE,BUF1)
*
* TO GET THE DESCRIPTOR PARAMETERS FROM THE REPORT THAT WAS READ
* AND USE THEM FOR INITIALIZING A NEW REPORT.
*
ISTAT = MRBHDR(BUF1,TEMPS,FLGS,STNID,IDTYP,LATI,LONG,DX,DY,
1 ELEV,DRND,DATE,OARS,RUNN,NBLOCS,SUP,0,XAUX,0)
*
ISTAT = MRBINI(20,BUF2,TEMPS,FLGS,STNID,IDTYP,LATI,LONG,DX,DY,
1 ELEV,DRND,DATE,OARS,RUNN,SUP,0,XAUX,0)
*
* TO FIND ALL THE BLOCKS OF TYPE BTYP=12, EXTRACT THEM,
* MAKE A NEW REPORT FOR THE FILE (UNIT 20)
*
BLKNO = 0
BLKNO = MRBLOC(BUF1,-1,-1,12,BLKNO)
2000 IF(BLKNO .GT. 0) THEN
* READ THE BLOCK
ISTAT = MRBXTR(BUF1,BLKNO,LSTELE,TBLVAL)
* EXTRACTING PARAMETER DESCRIPTORS FROM THE BLOCK
ISTAT = MRBPRM(BUF1,BLKNO,NELE,NVAL,NT,BFAM,BDESC,
1 BTYP,NBIT,BIT0,DATYP)
* WRITE THE BLOCK IN BUF2
ISTAT = MRBADD(BUF2,IBLOC,NELE,NVAL,NT,BFAM,BDESC,
1 BTYP,NBIT,BIT0,DATYP,LSTELE,TBLVAL)
* LOCATE THE NEXT BLOCK OF SAME TYPE
BLKNO = MRBLOC(BUF1,-1,-1,12,BLKNO)
GOTO 2000
ENDIF
*
* TO WRITE THE NEW REPORT IN THE FILE BURP20
*
ISTAT = MRFPUT(20,0,BUF2)
*
* TO FIND THE NEXT REPORT
*
HANDLE = MRFLOC(10,HANDLE,'STATION01',-1,-1,-1,120691,
1 1200,SUP,0)
GOTO 1000
ENDIF
* CLOSE FILES
*
ISTAT = MRFCLS(10)
ISTAT = MRFCLS(20)
STOP
END
SPECIALISTS
Mario Lepine -RPN- 421-4738
Michel Valin -RPN- 421-4753
Documentation by Vivian Lee,RPN,Dorval,421-4743
NOTE:
SEE ALSO reflex, xdf, editbrp in the RPN documentation in the WEBSITE:
You can also consult the document describing BANCO which is the data BANk of quality COntrol and analysis.