NCEPLIBS-bufr  12.1.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 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 NEMO_STR_LEN   8
 Size of a character string needed to store a mnemonic. More...
 
#define UNIT_STR_LEN   24
 Size of a character string needed to store the units of a Table B descriptor. More...
 

Functions

void arallocc (void)
 Dynamically allocate C language arrays. More...
 
void ardllocc (void)
 Free all memory that was dynamically allocated during a previous call to subroutine arallocc(). More...
 
void backbufr (int nfile)
 Backspace a BUFR file by one BUFR message. 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...
 
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...
 

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 34 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 43 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 37 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 40 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 46 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 49 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, iafpk, ibfxyn_c, idefxy_c, idfxyn_c, igetprm_f(), lstpos, ndelem_c, and pb.

◆ ardllocc()

void ardllocc ( void  )

Free all memory that was dynamically allocated during a previous call to subroutine arallocc().

Author
J. Ator
Date
2014-12-04

Definition at line 90 of file arallocc.c.

References cbbw_c, cbelem_c, cbmnem_c, cbscl_c, cbsref_c, cbunit_c, cdmnem_c, cdseq_c, iafpk, 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_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(), restd(), 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().

◆ 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- WMO 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 73 of file restd.c.

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

Referenced by restd().

◆ 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 WMO bit-wise (integer) representation of a 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 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 107 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, iafpk, icvidx(), idefxy_c, ifxy_f(), igetntbi_f(), igetprm_f(), igettdi_f(), imrkopr_f(), MAX_FXY_TABLEB, MIN_FXY_REPL, MIN_FXY_TABLED, ndelem_c, NEMO_STR_LEN, nemtab_f(), nummtb(), numtbd_f(), pktdd_f(), stntbi_f(), strnum_f(), and stseq().

Referenced by stseq().

◆ 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().