NCEPLIBS-bufr  12.0.0
bufrlib.h File Reference

Enable a number of NCEPLIBS-bufr subprograms to be called from within the C part of the library. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include "bufr_interface.h"

Go to the source code of this file.

Macros

#define FXY_STR_LEN   6
 Size of a character string needed to store an FXY value. More...
 
#define MAX_FXY_TABLEB   "063255"
 Character string containing maximum FXY value for a Table B descriptor. More...
 
#define MAXCD   250
 Maximum number of child descriptors that can be included within the sequence definition of a Table D descriptor, not counting the recursive resolution of any child descriptors which may themselves be Table D descriptors. More...
 
#define MAXNC   600
 Maximum number of descriptors within Section 3 of a BUFR message. More...
 
#define MIN_FXY_REPL   "101000"
 Character string containing minimum FXY value for a replication descriptor. More...
 
#define MIN_FXY_TABLED   "300000"
 Character string containing minimum FXY value for a Table D descriptor. More...
 
#define MXNAF   4
 Maximum number of associated fields that can be in effect at any given time for a Table B descriptor. More...
 
#define NEMO_STR_LEN   8
 Size of a character string needed to store a mnemonic. More...
 
#define NFILES   32
 Maximum number of BUFR files that can be connected to the NCEPLIBS-bufr software (for reading or writing) at any one time. More...
 
#define UNIT_STR_LEN   24
 Size of a character string needed to store the units of a Table B descriptor. More...
 
#define VERS_STR_LEN   8
 Size of a character string needed to store a library version number. More...
 

Functions

void arallocc (void)
 Dynamically allocate C language arrays. More...
 
void ardllocc (void)
 Free all dynamically-allocated memory within internal C language arrays. More...
 
void backbufr (int nfile)
 Backspace a BUFR file by one BUFR message. More...
 
void bort_exit (void)
 This subroutine terminates the application program with a non-zero status code. More...
 
void bort_f (char *errstr)
 Log one error message and abort application program. More...
 
void cadn30_f (int idn, char *adn, int adn_str_len)
 Convert an FXY value from its WMO bit-wise representation to its six-character representation. More...
 
void cewind (int nfile)
 Rewind a BUFR file back to its beginning. More...
 
void closfb (int nfile)
 Close a previously opened BUFR file. More...
 
int crdbufr (int nfile, int *bufr, int mxwrd)
 Read the next message from a BUFR file that was previously opened for reading. More...
 
void cwrbufr (int nfile, int *bufr, int nwrd)
 Write a BUFR message into a file that was previously opened for writing. More...
 
void elemdx_f (char *card, int lun)
 Decode the scale factor, reference value, bit width, and units from a Table B mnemonic definition. More...
 
int icvidx (int ii, int jj, int numjj)
 Computes a unique 1-dimensional array index from 2-dimensional indices. More...
 
int ifxy_f (char *cfxy)
 Convert an FXY value from its 6 character representation to its WMO bit-wise representation. More...
 
int igetntbi_f (int lun, char *table_type)
 Get the next index for storing an entry within an internal DX BUFR table. More...
 
int igettdi_f (int iflag)
 Get the next usable Table D index for the current master table, or reset the index. More...
 
int imrkopr_f (char *nemo)
 Check whether a specified mnemonic is a Table C marker operator. More...
 
int istdesc_f (int idn)
 Check whether a descriptor is WMO-standard. More...
 
int iupb_f (int *mbay, int nbyt, int nbit)
 Decode an integer value from an integer array. More...
 
void numtbd_f (int lun, int idn, char *nemo, int nemo_str_len, char *tab, int *iret)
 Search for a Table B or Table D descriptor within the internal DX BUFR tables. More...
 
void openab (int nfile, char *ufile)
 Open a new file for appending BUFR messages. More...
 
void openrb (int nfile, char *ufile)
 Open a new file for reading BUFR messages. More...
 
void openwb (int nfile, char *ufile)
 Open a new file for writing BUFR messages. More...
 
void pktdd_f (int id, int lun, int idn, int *iret)
 Store information about a child mnemonic within the internal arrays. More...
 
void restd (int lunb, int tddesc, int *nctddesc, int *ctddesc)
 Standardize a local Table D descriptor. More...
 
void stntbi_f (int n, int lun, char *numb, char *nemo, char *celsq)
 Store a new entry within the internal BUFR Table B or D. More...
 
void strnum_f (char *str, int *num, int *iret)
 Decode an integer from a character string. More...
 
void stseq (int lun, int *irepct, int idn, char *nemo, char *cseq, int *cdesc, int ncdesc)
 Store information about a standard Table D descriptor within internal DX BUFR tables. More...
 
void uptdd_f (int id, int lun, int ient, int *iret)
 Get the WMO bit-wise representation of the FXY value corresponding to a child mnemonic of a Table D sequence. More...
 
void wrdesc (int desc, int *descary, int *ndescary)
 Maintain an array of descriptors. More...
 
void wrdlen_f (void)
 Determine important information about the local machine. More...
 

Detailed Description

Enable a number of NCEPLIBS-bufr subprograms to be called from within the C part of the library.

This header file defines signatures which wrap a number of native Fortran subprograms in the library. It also contains prototypes for native C functions in the library as well as macros used throughout the C part of the library.

Author
J. Ator
Date
2003-11-04

Definition in file bufrlib.h.

Macro Definition Documentation

◆ FXY_STR_LEN

#define FXY_STR_LEN   6

Size of a character string needed to store an FXY value.

Definition at line 54 of file bufrlib.h.

◆ MAX_FXY_TABLEB

#define MAX_FXY_TABLEB   "063255"

Character string containing maximum FXY value for a Table B descriptor.

Definition at line 63 of file bufrlib.h.

◆ MAXCD

#define MAXCD   250

Maximum number of child descriptors that can be included within the sequence definition of a Table D descriptor, not counting the recursive resolution of any child descriptors which may themselves be Table D descriptors.

Definition at line 43 of file bufrlib.h.

◆ MAXNC

#define MAXNC   600

Maximum number of descriptors within Section 3 of a BUFR message.

Definition at line 47 of file bufrlib.h.

◆ MIN_FXY_REPL

#define MIN_FXY_REPL   "101000"

Character string containing minimum FXY value for a replication descriptor.

Definition at line 57 of file bufrlib.h.

◆ MIN_FXY_TABLED

#define MIN_FXY_TABLED   "300000"

Character string containing minimum FXY value for a Table D descriptor.

Definition at line 60 of file bufrlib.h.

◆ MXNAF

#define MXNAF   4

Maximum number of associated fields that can be in effect at any given time for a Table B descriptor.

Definition at line 51 of file bufrlib.h.

◆ NEMO_STR_LEN

#define NEMO_STR_LEN   8

Size of a character string needed to store a mnemonic.

Definition at line 66 of file bufrlib.h.

◆ NFILES

#define NFILES   32

Maximum number of BUFR files that can be connected to the NCEPLIBS-bufr software (for reading or writing) at any one time.

Definition at line 37 of file bufrlib.h.

◆ UNIT_STR_LEN

#define UNIT_STR_LEN   24

Size of a character string needed to store the units of a Table B descriptor.

Definition at line 69 of file bufrlib.h.

◆ VERS_STR_LEN

#define VERS_STR_LEN   8

Size of a character string needed to store a library version number.

Definition at line 72 of file bufrlib.h.

Function Documentation

◆ arallocc()

void arallocc ( void  )

Dynamically allocate C language arrays.

This subroutine is called internally during the first call to subroutine openbf() from an application program, in order to dynamically allocate internal C language arrays based on parameter values set during one or more previous calls to function isetprm().

All memory allocated within this subroutine can be freed via a subsequent call to subroutine exitbufr().

Author
J. Ator
Date
2014-12-04

Definition at line 29 of file arallocc.c.

References bort_f(), cbbw_c, cbelem_c, cbmnem_c, cbscl_c, cbsref_c, cbunit_c, cdmnem_c, cdseq_c, ibfxyn_c, idefxy_c, idfxyn_c, igetprm_f(), lstpos, modv_maxcd::maxcd, modv_mxmtbb::mxmtbb, modv_mxmtbd::mxmtbd, ndelem_c, modv_nfiles::nfiles, and pb.

◆ ardllocc()

void ardllocc ( void  )

Free all dynamically-allocated memory within internal C language arrays.

This subroutine frees any memory that was dynamically allocated during a previous call to subroutine arallocc().

Author
J. Ator
Date
2014-12-04

Definition at line 21 of file ardllocc.c.

References cbbw_c, cbelem_c, cbmnem_c, cbscl_c, cbsref_c, cbunit_c, cdmnem_c, cdseq_c, ibfxyn_c, idefxy_c, idfxyn_c, lstpos, ndelem_c, and pb.

◆ backbufr()

void backbufr ( int  nfile)

Backspace a BUFR file by one BUFR message.

Parameters
nfile- File ID.
Author
J. Woollen
Date
2012-09-15

Definition at line 68 of file cread.c.

References lstpos, and pb.

◆ bort_exit()

void bort_exit ( void  )

This subroutine terminates the application program with a non-zero status code.

Author
J. Ator
Date
2003-11-04

Definition at line 16 of file bort_exit.c.

◆ bort_f()

void bort_f ( char *  errstr)

Log one error message and abort application program.

Wraps bort() subroutine.

Parameters
errstr- Error message.
Author
J. Ator
Date
2023-04-07

Referenced by arallocc(), cobfl(), crbmg(), cwbmg(), inittbf(), nummtb(), strtbfe(), stseq(), and wrdesc().

◆ cadn30_f()

void cadn30_f ( int  idn,
char *  adn,
int  adn_str_len 
)

Convert an FXY value from its WMO bit-wise representation to its six-character representation.

Wraps cadn30() subroutine.

Parameters
idn- WMO bit-wise representation of FXY value.
adn- FXY value.
adn_str_len- Length of adn string.
Author
J. Ator
Date
2004-08-18

Referenced by nummtb(), restd(), and stseq().

◆ cewind()

void cewind ( int  nfile)

Rewind a BUFR file back to its beginning.

Parameters
nfile- File ID.
Author
J. Woollen
Date
2012-09-15

Definition at line 80 of file cread.c.

References pb.

◆ closfb()

void closfb ( int  nfile)

Close a previously opened BUFR file.

Parameters
nfile- File ID.
Author
J. Woollen
Date
2012-09-15

Definition at line 92 of file cread.c.

References pb.

◆ crdbufr()

int crdbufr ( int  nfile,
int *  bufr,
int  mxwrd 
)

Read the next message from a BUFR file that was previously opened for reading.

Parameters
nfile- File ID.
bufr- BUFR message.
mxwrd- Number of elements in bufr array; used by the function to ensure that it doesn't overflow the array.
Returns
  • 0 normal return.
  • -1 end-of-file encountered while reading.
  • -2 I/O error encountered while reading.
  • -3 overflow of bufr array.
Author
J. Woollen
Date
2012-09-15

Definition at line 114 of file cread.c.

References iupbs01_f(), lstpos, and pb.

◆ cwrbufr()

void cwrbufr ( int  nfile,
int *  bufr,
int  nwrd 
)

Write a BUFR message into a file that was previously opened for writing.

Parameters
nfile- File ID.
bufr- BUFR message.
nwrd- Size (in integers) of bufr.
Author
J. Woollen
Date
2012-09-15

Definition at line 199 of file cread.c.

References pb.

◆ elemdx_f()

void elemdx_f ( char *  card,
int  lun 
)

Decode the scale factor, reference value, bit width, and units from a Table B mnemonic definition.

Wraps elemdx() subroutine.

Parameters
card- mnemonic definition card.
lun- File ID.
Author
J. Ator
Date
2003-11-04

Referenced by stseq().

◆ icvidx()

int icvidx ( int  ii,
int  jj,
int  numjj 
)

Computes a unique 1-dimensional array index from 2-dimensional indices.

This allows a 2-dimensional (row-by-column) array to be stored and accessed as a 1-dimensional array.

Parameters
ii- first (row) index
jj- second (column) index
numjj- maximum number of column indices
Returns
1-dimensional index.
Author
J. Ator
Date
2009-03-23

Definition at line 22 of file icvidx.c.

Referenced by cpmstabs(), and stseq().

◆ ifxy_f()

int ifxy_f ( char *  cfxy)

Convert an FXY value from its 6 character representation to its WMO bit-wise representation.

Wraps ifxy() function.

Parameters
cfxy- FXY value.
Returns
WMO bit-wise representation of FXY value.
Author
J. Ator
Date
2023-04-07

Referenced by nummtb(), restd(), and stseq().

◆ igetntbi_f()

int igetntbi_f ( int  lun,
char *  table_type 
)

Get the next index for storing an entry within an internal DX BUFR table.

Wraps igetntbi() function.

Parameters
lun- File ID.
table_type- Type of internal DX BUFR table ('A', 'B', or 'D').
Returns
Next available index within table_type.
Author
J. Ator
Date
2009-03-23

Referenced by stseq().

◆ igettdi_f()

int igettdi_f ( int  iflag)

Get the next usable Table D index for the current master table, or reset the index.

Wraps igettdi() function.

Parameters
iflag- Processing flag; if 0 will reset the index.
Returns
  • -1, if iflag was input as 0.
  • next usable scratch Table D index, otherwise.
Author
J. Ator
Date
2009-03-23

Referenced by stseq().

◆ imrkopr_f()

int imrkopr_f ( char *  nemo)

Check whether a specified mnemonic is a Table C marker operator.

Wraps imrkopr() function.

Parameters
nemo- Mnemonic.
Returns
  • 0 nemo is not a Table C marker operator.
  • 1 nemo is a Table C marker operator.
Author
J. Ator
Date
2016-05-04

Referenced by stseq().

◆ istdesc_f()

int istdesc_f ( int  idn)

Check whether a descriptor is WMO-standard.

Wraps istdesc() function.

Parameters
idn- WMO bit-wise representation of FXY value for descriptor.
Returns
  • 0 idn is not a WMO-standard descriptor.
  • 1 idn is a WMO-standard descriptor.
Author
J. Ator
Date
2004-08-18

Referenced by restd().

◆ iupb_f()

int iupb_f ( int *  mbay,
int  nbyt,
int  nbit 
)

Decode an integer value from an integer array.

Wraps iupb() function.

Parameters
mbay- Array containing encoded value.
nbyt- Byte within mbay at whose first bit to begin decoding.
nbit- Number of bits to decode.
Returns
Decoded value.
Author
J. Ator
Date
2003-11-04

Referenced by main().

◆ numtbd_f()

void numtbd_f ( int  lun,
int  idn,
char *  nemo,
int  nemo_str_len,
char *  tab,
int *  iret 
)

Search for a Table B or Table D descriptor within the internal DX BUFR tables.

Wraps numtbd() subroutine.

Parameters
lun- File ID.
idn- Bit-wise representation of FXY value.
nemo- Mnemonic.
nemo_str_len- Length of nemo string.
tab- Type of internal DX BUFR table ('B', or 'D').
iret- Positional index of idn within Table B or D, or 0 if not found.
Author
J. Ator
Date
2003-11-04

Referenced by restd(), and stseq().

◆ openab()

void openab ( int  nfile,
char *  ufile 
)

Open a new file for appending BUFR messages.

Parameters
nfile- File ID.
ufile- [path/]name of file to be opened.
Author
J. Woollen
Date
2012-09-15

Definition at line 56 of file cread.c.

References pb.

◆ openrb()

void openrb ( int  nfile,
char *  ufile 
)

Open a new file for reading BUFR messages.

Parameters
nfile- File ID.
ufile- [path/]name of file to be opened.
Author
J. Woollen
Date
2012-09-15

Definition at line 30 of file cread.c.

References pb.

◆ openwb()

void openwb ( int  nfile,
char *  ufile 
)

Open a new file for writing BUFR messages.

Parameters
nfile- File ID.
ufile- [path/]name of file to be opened.
Author
J. Woollen
Date
2012-09-15

Definition at line 43 of file cread.c.

References pb.

◆ pktdd_f()

void pktdd_f ( int  id,
int  lun,
int  idn,
int *  iret 
)

Store information about a child mnemonic within the internal arrays.

Wraps pktdd() subroutine.

Parameters
id- Index of parent mnemonic within internal arrays.
lun- File ID.
idn- WMO bit-wise representation of FXY value for child mnemonic, or 0 to delete all child mnemonic information for parent mnemonic id.
iret- 0 if idn=0; -1 if error occurred; otherwise, the total number of child mnemonics stored so far for parent mnemonic id.
Author
J. Ator
Date
2003-11-04

Referenced by stseq().

◆ restd()

void restd ( int  lun,
int  tddesc,
int *  nctddesc,
int *  ctddesc 
)

Standardize a local Table D descriptor.

Given the bit-wise (integer) representation of a local (not WMO-standard) Table D descriptor, this subroutine returns an equivalent array of WMO-standard child descriptors.

Any child descriptors which are themselves local Table D descriptors are automatically resolved via a recursive call to this same subroutine. This recursive process continues until all child descriptors are either WMO-standard descriptors (from Table B, Table C, Table D, or replication descriptors) or else are local Table B descriptors, in which case they are preceded with an appropriate 2-06-YYY Table C operator in the output array. The output array is then useable by any standard BUFR decoder program in order to interpret the same data values as were represented by the input local Table D descriptor.

Parameters
lun- File ID.
tddesc- WMO bit-wise representation of FXY value for local Table D descriptor.
nctddesc- Number of WMO-standard child descriptors returned in ctddesc.
ctddesc- Array of WMO-standard child descriptors equivalent to tddesc.
Author
J. Ator
Date
2004-08-18

Definition at line 39 of file restd.c.

References cadn30_f(), FXY_STR_LEN, moda_bitbuf::ibit, ifxy_f(), istdesc_f(), MAXNC, MIN_FXY_REPL, NEMO_STR_LEN, nemtbb_f(), numtbd_f(), UNIT_STR_LEN, uptdd_f(), and wrdesc().

◆ stntbi_f()

void stntbi_f ( int  n,
int  lun,
char *  numb,
char *  nemo,
char *  celsq 
)

Store a new entry within the internal BUFR Table B or D.

Wraps stntbi() subroutine.

Parameters
n- Storage index into internal Table B or D.
lun- File ID.
numb- FXY number for new entry.
nemo- mnemonic corresponding to numb.
celsq- Element or sequence definition corresponding to numb.
Author
J. Ator
Date
2009-03-23

Referenced by stseq().

◆ strnum_f()

void strnum_f ( char *  str,
int *  num,
int *  iret 
)

Decode an integer from a character string.

Wraps strnum() subroutine.

Parameters
str- String.
num- Value decoded from str.
iret- Return code: 0 if successful, -1 otherwise.
Author
J. Ator
Date
2003-11-04

Referenced by stseq().

◆ stseq()

void stseq ( int  lun,
int *  irepct,
int  idn,
char *  nemo,
char *  cseq,
int *  cdesc,
int  ncdesc 
)

Store information about a standard Table D descriptor within internal DX BUFR tables.

Given the bit-wise (integer) representation of a WMO-standard Table D descriptor, this subroutine uses the master BUFR tables to store all of the necessary information for that descriptor within the internal DX BUFR tables. Any child descriptors which are themselves Table D descriptors are automatically resolved via a recursive call to this same subroutine.

Parameters
lun- File ID.
irepct- Replication sequence counter for the current master table; used internally to keep track of which sequence names have already been defined, and thereby avoid contention within the internal DX BUFR Table D.
idn- WMO bit-wise representation of FXY value for WMO-standard Table D descriptor
nemo- Mnemonic corresponding to idn.
cseq- Description corresponding to idn.
cdesc- Array of WMO-standard child descriptors equivalent to idn.
ncdesc- Number of WMO-standard child descriptors in cdesc.
Author
J. Ator
Date
2009-03-23

Definition at line 111 of file stseq.c.

References bort_f(), cadn30_f(), cbbw_c, cbelem_c, cbmnem_c, cbscl_c, cbsref_c, cbunit_c, cdmnem_c, cdseq_c, elemdx_f(), FXY_STR_LEN, icvidx(), idefxy_c, ifxy_f(), igetntbi_f(), igetprm_f(), igettdi_f(), imrkopr_f(), MAX_FXY_TABLEB, MIN_FXY_REPL, MIN_FXY_TABLED, MXNAF, ndelem_c, NEMO_STR_LEN, nemtab_f(), nummtb(), numtbd_f(), pktdd_f(), stntbi_f(), and strnum_f().

◆ uptdd_f()

void uptdd_f ( int  id,
int  lun,
int  ient,
int *  iret 
)

Get the WMO bit-wise representation of the FXY value corresponding to a child mnemonic of a Table D sequence.

Wraps uptdd() subroutine.

Parameters
id- Positional index of parent mnemonic within internal Table D.
lun- File ID.
ient- Ordinal indicator of child mnemonic to be returned, or 0 to request a count of the total number of child mnemonics.
iret- Total number of child mnemonics if ient = 0; otherwise the WMO bit-wise representation of the FXY value corresponding to the ient'th mnemonic.
Author
J. Ator
Date
2003-11-04

Referenced by restd().

◆ wrdesc()

void wrdesc ( int  desc,
int *  descary,
int *  ndescary 
)

Maintain an array of descriptors.

Given the WMO bit-wise representation of a descriptor, this routine adds it to an ongoing array of descriptors, after first making sure that there is enough room in the array.

If an array overflow occurs, then an appropriate error message will be written via bort().

Parameters
desc- WMO bit-wise representation of descriptor to be written into descary.
descary- Array of descriptors.
ndescary- Number of descriptors written so far into descary.
Author
J. Ator
Date
2004-08-18

Definition at line 27 of file wrdesc.c.

References bort_f(), and MAXNC.

Referenced by restd().

◆ wrdlen_f()

void wrdlen_f ( void  )

Determine important information about the local machine.

Wraps wrdlen() subroutine.

Author
J. Ator
Date
2023-04-07

Referenced by cobfl(), and main().