NCEPLIBS-bufr  12.0.0
bufr_interface.h File Reference

Enable a number of NCEPLIBS-bufr subprograms to be called from within C and C++ application programs. More...

Go to the source code of this file.

Functions

void bvers_f (char *cverstr, int cverstr_len)
 Get the version number of the NCEPLIBS-bufr software. More...
 
void ccbfl (void)
 Close all files that were opened via previous calls to function cobfl(). More...
 
void closbf_f (int bufr_unit)
 Close a previously opened file and disconnect it from the library. More...
 
void close_f (int unit)
 Close a Fortran file from a C program. More...
 
void cmpmsg_f (char *cf)
 Specify the use of compression when writing BUFR messages. More...
 
void cobfl (char *bfl, char io)
 Open a new file for reading or writing BUFR messages via a C language interface. More...
 
void crbmg (char *bmg, int mxmb, int *nmb, int *iret)
 Read the next BUFR message from the file that was opened via the most recent call to function cobfl() with io = 'r'. More...
 
void cwbmg (char *bmg, int nmb, int *iret)
 Write a BUFR message to the file that was opened via the most recent call to function cobfl() with io = 'w'. More...
 
void delete_table_data_f ()
 Deletes the copies of the moda_tables arrays. More...
 
void exitbufr_f ()
 Reset the library. More...
 
void get_inode_f (int lun, int *start_node)
 Get the bufr node idx for the start node of the subset. More...
 
void get_inv_f (int lun, int **inv_ptr, int *inv_size)
 Get pointer to the moda_usrint INV array. More...
 
void get_irf_f (int **irf_ptr, int *irf_size)
 Get copy of the moda_tables IRF array. More...
 
void get_isc_f (int **isc_ptr, int *isc_size)
 Get copy of the moda_tables ISC array. More...
 
void get_itp_f (int **itp_ptr, int *itp_size)
 Get copy of the moda_tables ITP array. More...
 
void get_jmpb_f (int **jmpb_ptr, int *jmpb_size)
 Get copy of the moda_tables JMPB array. More...
 
void get_link_f (int **link_ptr, int *link_size)
 Get copy of the moda_tables LINK array. More...
 
void get_nval_f (int lun, int *num_nodes)
 Get the number of values in the current subset. More...
 
void get_tag_f (char **tag_ptr, int *tag_len, int *mem_size)
 Get copy of the moda_tables TAG array. More...
 
void get_typ_f (char **typ_ptr, int *typ_len, int *mem_size)
 Get copy of the moda_tables TYP array. More...
 
void get_val_f (int lun, double **val_ptr, int *val_size)
 Get pointer to the moda_usrint VAL array. More...
 
int ibfms_f (double r8val)
 Test whether a data value is "missing". More...
 
int igetmxby_f (void)
 Get the maximum length of a BUFR message that can be written to an output file. More...
 
int igetprm_f (char *cprmnm)
 Get the current value of a parameter. More...
 
int ireadmg_f (int bufr_unit, char *subset, int *iddate, int subset_len)
 Read the next message from a BUFR file. More...
 
int ireadns_f (int bufr_unit, char *subset, int *iddate, int subset_len)
 Read the next data subset from a BUFR file. More...
 
int ireadsb_f (int bufr_unit)
 Read the next data subset from a BUFR message. More...
 
int isetprm_f (char *cprmnm, int ipval)
 Define a customized parameter value for dynamic allocation. More...
 
int iupbs01_f (int *bufr, char *mnemonic)
 Read a data value from Section 0 or Section 1 of a BUFR message. More...
 
void maxout_f (int max0)
 Define a customized maximum length for output BUFR messages. More...
 
void mtinfo_f (const char *path, int file_unit_1, int file_unit_2)
 Specify location of master BUFR tables on local file system. More...
 
void nemdefs_f (int file_unit, const char *mnemonic, char *unit_c, int unit_str_len, char *desc_c, int desc_str_len, int *iret)
 Get the element name and units associated with a Table B mnemonic. More...
 
void nemspecs_f (int file_unit, const char *mnemonic, int mnemonic_idx, int *scale, int *reference, int *bits, int *iret)
 Get the scale factor, reference value and bit width associated with a specified occurrence of a Table B mnemonic. More...
 
void nemtab_f (int lun, const char *mnemonic, int *descriptor, char *table_type, int *table_idx)
 Get information about a descriptor. More...
 
void nemtbb_f (int lun, int table_idx, char *unit_str, int unit_str_len, int *scale, int *reference, int *bits)
 Get information about a Table B descriptor. More...
 
void open_f (int unit, const char *filepath)
 Open a Fortran file from a C program. More...
 
void openbf_f (int bufr_unit, const char *cio, int table_file_id)
 Connect a new file to the library, or initialize the library, or change verbosity associated with already-connected file. More...
 
void openmb_f (int bufr_unit, char *c_subset, int iddate)
 Open a new message for output in a BUFR file that was previously opened for writing. More...
 
void status_f (int file_unit, int *lun, int *il, int *im)
 Check whether a file is connected to the library. More...
 
void ufbint_f (int bufr_unit, void **c_data, int dim_1, int dim_2, int *iret, const char *table_b_mnemonic)
 Read/write one or more data values from/to a data subset. More...
 
void ufbrep_f (int bufr_unit, void **c_data, int dim_1, int dim_2, int *iret, const char *table_b_mnemonic)
 Read/write one or more data values from/to a data subset. More...
 
void ufbseq_f (int bufr_unit, void **c_data, int dim_1, int dim_2, int *iret, const char *table_d_mnemonic)
 Read/write an entire sequence of data values from/to a data subset. More...
 

Detailed Description

Enable a number of NCEPLIBS-bufr subprograms to be called from within C and C++ application programs.

This header file defines the signatures which wrap a number of native Fortran subprograms in the library. It also contains prototypes for native C functions in the library which are expected to be called from C and C++ application programs.

Author
Ronald Mclaren
Date
2020-07-29

Definition in file bufr_interface.h.

Function Documentation

◆ bvers_f()

void bvers_f ( char *  cverstr,
int  cverstr_len 
)

Get the version number of the NCEPLIBS-bufr software.

Wraps bvers() subroutine.

Parameters
cverstr- Version string.
cverstr_len- Length of version string.
Author
J. Ator
Date
2023-04-07

Referenced by main().

◆ ccbfl()

void ccbfl ( void  )

Close all files that were opened via previous calls to function cobfl().

Author
J. Ator
Date
2005-11-29

Definition at line 296 of file crwbmg.c.

References pbf.

Referenced by main().

◆ closbf_f()

void closbf_f ( int  bufr_unit)

Close a previously opened file and disconnect it from the library.

Wraps closbf() subroutine.

Parameters
bufr_unit- the Fortran logical unit number to close.
Author
Ronald Mclaren
Date
2020-07-29

◆ close_f()

void close_f ( int  unit)

Close a Fortran file from a C program.

Parameters
unit- the integer to use as the Fortran logical unit.
Author
Ronald Mclaren
Date
2020-07-29

◆ cmpmsg_f()

void cmpmsg_f ( char *  cf)

Specify the use of compression when writing BUFR messages.

Wraps cmpmsg() subroutine.

Parameters
cf- Flag indicating whether future BUFR output messages are to be compressed ('Y' = Yes, 'N' = No).
Author
J. Ator
Date
2023-04-07

◆ cobfl()

void cobfl ( char *  bfl,
char  io 
)

Open a new file for reading or writing BUFR messages via a C language interface.

This function is designed to be easily callable from application program written in either C or Fortran. It is functionally equivalent to subroutine openbf(); however, there are some important differences:

  • When using openbf(), the underlying file must already be associated with a Fortran logical unit number on the local system, typicially via a prior Fortran "OPEN" statement. This is not required when using this function.
  • When using this function, it is only possible to have at most one input (io = 'r') file and one output (io = 'w') file open at a time. If a successive call to this function is made in either case where a file of that type is already open, then the function will automatically close the previous file of that type before opening the new one.
  • When opening a file for input/reading using openbf(), the user can make subsequent calls to any of the NCEPLIBS-bufr message-reading subroutines to read individual BUFR messages from that file into internal arrays, followed by subsequent calls to any of the NCEPLIBS-bufr subset-reading subroutines") to read individual data subsets from each such message. However, when opening a file for input/reading using this function, the user must instead make subsequent calls to crbmg() to read individual BUFR messages from that file, and each such message will be returned directly to the user within an allocated memory array. The user may then, if desired, make subsequent calls to readerme() to store each such message into the same internal arrays, followed by subsequent calls to any of the NCEPLIBS-bufr subset-reading subroutines" to read individual data subsets from each such message.
  • When opening a file for output/writing using openbf(), the user can make subsequent successive calls to writsb() to pack each completed data subset into the BUFR message that is currently open within the internal arrays, for eventual output to that file. However, when opening a file for output/writing using this function, the user can instead, if desired, make subsequent successive calls to writsa() to pack each completed data subset into the BUFR message that is currently open within the internal arrays. The use of writsa() will cause each completed BUFR message to be returned directly to the user within an allocated memory array, which in turn can then be written directly to the file via a subsequent call to cwbmg().

Any errors encountered when using this function are automatically logged to standard output, or to an alternate location previously specified via a call to subroutine errwrt().

Parameters
bfl- System file to be opened. Inclusion of directory prefixes or other local filesystem notation is allowed, up to 200 total characters.
io- Flag indicating how bfl is to be opened:
  • 'r' input (for reading BUFR messages)
  • 'w' output (for writing BUFR messages)
Author
J. Ator
Date
2005-11-29

Definition at line 120 of file crwbmg.c.

References bort_f(), MXFNLEN, pbf, and wrdlen_f().

Referenced by main().

◆ crbmg()

void crbmg ( char *  bmg,
int  mxmb,
int *  nmb,
int *  iret 
)

Read the next BUFR message from the file that was opened via the most recent call to function cobfl() with io = 'r'.

This function is designed to be easily callable from application program written in either C or Fortran.

Parameters
bmg- BUFR message
mxmb- Number of elements in bmg array;; used by the function to ensure that it doesn't overflow the array.
nmb- Size (in bytes) of BUFR message in bmg.
iret- return code:
  • 0 normal return.
  • 1 overflow of bmg array.
  • 2 "7777" indicator not found in expected location.
  • -1 end-of-file encountered while reading.
  • -2 I/O error encountered while reading.
Author
J. Ator
Date
2005-11-29

Definition at line 201 of file crwbmg.c.

References bort_f(), iupbs01_f(), pbf, and rbytes().

◆ cwbmg()

void cwbmg ( char *  bmg,
int  nmb,
int *  iret 
)

Write a BUFR message to the file that was opened via the most recent call to function cobfl() with io = 'w'.

This function is designed to be easily callable from application program written in either C or Fortran.

Parameters
bmg- BUFR message
nmb- Size (in bytes) of BUFR message in bmg
iret- return code:
  • 0 normal return.
  • -1 I/O error encountered while writing.
Author
J. Ator
Date
2005-11-29

Definition at line 269 of file crwbmg.c.

References bort_f(), and pbf.

◆ delete_table_data_f()

void delete_table_data_f ( )

Deletes the copies of the moda_tables arrays.

Author
Ronald McLaren
Date
2022-03-23

◆ exitbufr_f()

void exitbufr_f ( )

Reset the library.

Wraps exitbufr() subroutine.

Author
Ronald Mclaren
Date
2020-07-29

◆ get_inode_f()

void get_inode_f ( int  lun,
int *  start_node 
)

Get the bufr node idx for the start node of the subset.

Parameters
lun- File ID.
start_node- the start node of the subset.
Author
Ronald McLaren
Date
2022-03-23

◆ get_inv_f()

void get_inv_f ( int  lun,
int **  inv_ptr,
int *  inv_size 
)

Get pointer to the moda_usrint INV array.

Parameters
lun- File ID.
inv_ptr- pointer to a pointer to the INV array.
inv_size- size of the INV array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_irf_f()

void get_irf_f ( int **  irf_ptr,
int *  irf_size 
)

Get copy of the moda_tables IRF array.

Parameters
irf_ptr- pointer to a pointer to the IRF array.
irf_size- size of the IRF array.
Author
Ronald McLaren
Date
2023-04-05

◆ get_isc_f()

void get_isc_f ( int **  isc_ptr,
int *  isc_size 
)

Get copy of the moda_tables ISC array.

Parameters
isc_ptr- pointer to a pointer to the ISC array.
isc_size- size of the ISC array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_itp_f()

void get_itp_f ( int **  itp_ptr,
int *  itp_size 
)

Get copy of the moda_tables ITP array.

Parameters
itp_ptr- pointer to a pointer to the ITP array.
itp_size- size of the ITP array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_jmpb_f()

void get_jmpb_f ( int **  jmpb_ptr,
int *  jmpb_size 
)

Get copy of the moda_tables JMPB array.

Parameters
jmpb_ptr- pointer to a pointer to the JMPB array.
jmpb_size- size of the JMPB array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_link_f()

void get_link_f ( int **  link_ptr,
int *  link_size 
)

Get copy of the moda_tables LINK array.

Parameters
link_ptr- pointer to a pointer to the LINK array.
link_size- size of the LINK array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_nval_f()

void get_nval_f ( int  lun,
int *  num_nodes 
)

Get the number of values in the current subset.

Parameters
lun- File ID.
num_nodes- number of values in the subset.
Author
Ronald McLaren
Date
2022-03-23

◆ get_tag_f()

void get_tag_f ( char **  tag_ptr,
int *  tag_len,
int *  mem_size 
)

Get copy of the moda_tables TAG array.

Parameters
tag_ptr- pointer to a pointer to the TAG array.
tag_len- size of each string within the TAG array.
mem_size- size of the TAG array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_typ_f()

void get_typ_f ( char **  typ_ptr,
int *  typ_len,
int *  mem_size 
)

Get copy of the moda_tables TYP array.

Parameters
typ_ptr- pointer to a pointer to the TYP array.
typ_len- size of each string within the TYP array.
mem_size- size of the TYP array.
Author
Ronald McLaren
Date
2022-03-23

◆ get_val_f()

void get_val_f ( int  lun,
double **  val_ptr,
int *  val_size 
)

Get pointer to the moda_usrint VAL array.

Parameters
lun- File ID.
val_ptr- pointer to a pointer to the VAL array.
val_size- size of the VAL array.
Author
Ronald McLaren
Date
2022-03-23

◆ ibfms_f()

int ibfms_f ( double  r8val)

Test whether a data value is "missing".

Wraps ibfms() function.

Parameters
r8val- Data value.
Returns
- 1 if r8val is "missing", or 0 otherwise.
Author
J. Ator
Date
2023-04-07

◆ igetmxby_f()

int igetmxby_f ( void  )

Get the maximum length of a BUFR message that can be written to an output file.

Returns
Maximum length of a BUFR message that can be written to an output file.
Author
J. Ator
Date
2023-04-07

◆ igetprm_f()

int igetprm_f ( char *  cprmnm)

Get the current value of a parameter.

Parameters
cprmnm- Parameter.
Returns
Value of cprmnm.
Author
J. Ator
Date
2023-04-07

Referenced by arallocc(), inittbf(), and stseq().

◆ ireadmg_f()

int ireadmg_f ( int  bufr_unit,
char *  subset,
int *  iddate,
int  subset_len 
)

Read the next message from a BUFR file.

Wraps ireadmg() function.

Parameters
bufr_unit- the Fortran logical unit number to read from.
subset- the subset string.
iddate- datetime of message.
subset_len- length of the subset string.
Returns
  • 0 new BUFR message was successfully read into internal arrays.
  • -1 there are no more BUFR messages in bufr_unit.
Author
Ronald Mclaren
Date
2020-07-29

◆ ireadns_f()

int ireadns_f ( int  bufr_unit,
char *  subset,
int *  iddate,
int  subset_len 
)

Read the next data subset from a BUFR file.

Wraps ireadns() function.

Parameters
bufr_unit- the Fortran logical unit number to read from.
subset- the subset string.
iddate- datetime of message.
subset_len- length of the subset string.
Returns
  • 0 new BUFR data subset was successfully read into internal arrays.
  • -1 there are no more BUFR data subsets in bufr_unit.
Author
J. Ator
Date
2023-04-07

◆ ireadsb_f()

int ireadsb_f ( int  bufr_unit)

Read the next data subset from a BUFR message.

Wraps ireadsb() function.

Parameters
bufr_unit- the Fortran logical unit number to read from.
Returns
  • 0 new BUFR data subset was successfully read into internal arrays.
  • -1 there are no more BUFR data subsets in the BUFR message associated with bufr_unit
Author
Ronald Mclaren
Date
2020-07-29

◆ isetprm_f()

int isetprm_f ( char *  cprmnm,
int  ipval 
)

Define a customized parameter value for dynamic allocation.

Parameters
cprmnm- Parameter.
ipval- Value to be set for cprmnm.
Returns
0 if successful, or -1 if cprmnm unknown.
Author
J. Ator
Date
2023-04-07

◆ iupbs01_f()

int iupbs01_f ( int *  bufr,
char *  mnemonic 
)

Read a data value from Section 0 or Section 1 of a BUFR message.

Wraps iupbs01() function.

Parameters
bufr- BUFR message.
mnemonic- Value to be read from Section 0 or Section 1.
Returns
- Value corresponding to mnemonic, or -1 if not found or error occurred.
Author
J. Ator
Date
2023-04-07

Referenced by crbmg(), and crdbufr().

◆ maxout_f()

void maxout_f ( int  max0)

Define a customized maximum length for output BUFR messages.

Wraps maxout() subroutine.

Parameters
max0- New maximum length (in bytes) for all BUFR messages written to all output files.
Author
J. Ator
Date
2023-04-07

◆ mtinfo_f()

void mtinfo_f ( const char *  path,
int  file_unit_1,
int  file_unit_2 
)

Specify location of master BUFR tables on local file system.

Wraps mtinfo() subroutine.

Parameters
path- the path where the WMO tables are stored.
file_unit_1- number to use for first logical unit.
file_unit_2- number to use for second logical unit.
Author
Ronald Mclaren
Date
2020-07-29

◆ nemdefs_f()

void nemdefs_f ( int  file_unit,
const char *  mnemonic,
char *  unit_c,
int  unit_str_len,
char *  desc_c,
int  desc_str_len,
int *  iret 
)

Get the element name and units associated with a Table B mnemonic.

Wraps nemdefs() subroutine.

Parameters
file_unit- Fortran logical unit for the open file.
mnemonic- Mnemonic.
unit_c- Unit string.
unit_str_len- Unit string length.
desc_c- Description string.
desc_str_len- Description string length.
iret- 0 indicates success -1 indicates failure.
Author
Ronald Mclaren
Date
2020-07-29

◆ nemspecs_f()

void nemspecs_f ( int  file_unit,
const char *  mnemonic,
int  mnemonic_idx,
int *  scale,
int *  reference,
int *  bits,
int *  iret 
)

Get the scale factor, reference value and bit width associated with a specified occurrence of a Table B mnemonic.

Wraps nemspecs() subroutine.

Parameters
file_unit- Fortran logical unit for the open file.
mnemonic- Mnemonic.
mnemonic_idx- Ordinal indicator of specific mnemonic element (if repeated).
scale- Scale of element.
reference- Reference of element.
bits- Number of bits representing the element.
iret- 0 indicates success -1 indicates failure.
Author
Ronald Mclaren
Date
2022-08-08

◆ nemtab_f()

void nemtab_f ( int  lun,
const char *  mnemonic,
int *  descriptor,
char *  table_type,
int *  table_idx 
)

Get information about a descriptor.

Wraps nemtab() subroutine.

Parameters
lun- File ID.
mnemonic- Mnemonic.
descriptor- The binary descriptor for the mnemonic.
table_type- Type of internal DX BUFR table ('B', 'C', or 'D').
table_idx- The table index, or 0 if not found.
Author
Ronald Mclaren
Date
2022-08-16

Referenced by stseq().

◆ nemtbb_f()

void nemtbb_f ( int  lun,
int  table_idx,
char *  unit_str,
int  unit_str_len,
int *  scale,
int *  reference,
int *  bits 
)

Get information about a Table B descriptor.

Wraps nemtbb() subroutine.

Parameters
lun- File ID.
table_idx- Table B index.
unit_str- Unit string.
unit_str_len- Unit string length.
scale- Scale of element.
reference- Reference value of element.
bits- Number of bits representing theelement.
Author
Ronald McLaren
Date
2022-08-16

Referenced by restd().

◆ open_f()

void open_f ( int  unit,
const char *  filepath 
)

Open a Fortran file from a C program.

Parameters
unit- the integer to use as the Fortran logical unit.
filepath- path to the file we want to open.
Author
Ronald Mclaren
Date
2020-07-29

◆ openbf_f()

void openbf_f ( int  bufr_unit,
const char *  cio,
int  table_file_id 
)

Connect a new file to the library, or initialize the library, or change verbosity associated with already-connected file.

Wraps openbf() subroutine.

Parameters
bufr_unit- the Fortran logical unit number.
cio- cio string (ex "IN", "SEC3", and "OUT").
table_file_id- table_file unit number.
Author
Ronald Mclaren
Date
2020-07-29

◆ openmb_f()

void openmb_f ( int  bufr_unit,
char *  c_subset,
int  iddate 
)

Open a new message for output in a BUFR file that was previously opened for writing.

Wraps openmb() subroutine.

Parameters
bufr_unit- Fortran logical unit number to write to.
c_subset- Table A mnemonic of message.
iddate- Date-time to be stored within Section 1 of message.
Author
J. Ator
Date
2023-04-07

◆ status_f()

void status_f ( int  file_unit,
int *  lun,
int *  il,
int *  im 
)

Check whether a file is connected to the library.

Wraps status() subroutine.

Parameters
file_unit- Fortran logical unit number of file.
lun- File ID.
il- File status.
im- Message status.
Author
Ronald Mclaren
Date
2020-07-29

◆ ufbint_f()

void ufbint_f ( int  bufr_unit,
void **  c_data,
int  dim_1,
int  dim_2,
int *  iret,
const char *  table_b_mnemonic 
)

Read/write one or more data values from/to a data subset.

Wraps ufbint() subroutine.

Parameters
bufr_unit- the Fortran logical unit number to read from.
c_data- pointer to a pointer to a pre-allocated buffer.
dim_1- dimensionality of data to read or write.
dim_2- dimensionality of data to read or write.
iret- return value, length of data read.
table_b_mnemonic- string of mnemonics.
Author
Ronald Mclaren
Date
2020-07-29

◆ ufbrep_f()

void ufbrep_f ( int  bufr_unit,
void **  c_data,
int  dim_1,
int  dim_2,
int *  iret,
const char *  table_b_mnemonic 
)

Read/write one or more data values from/to a data subset.

Wraps ufbrep() subroutine.

Parameters
bufr_unit- the Fortran logical unit number to read from.
c_data- pointer to a pointer to a pre-allocated buffer.
dim_1- dimensionality of data to read or write.
dim_2- dimensionality of data to read or write.
iret- length of data read.
table_b_mnemonic- string of mnemonics.
Author
Ronald Mclaren
Date
2020-07-29

◆ ufbseq_f()

void ufbseq_f ( int  bufr_unit,
void **  c_data,
int  dim_1,
int  dim_2,
int *  iret,
const char *  table_d_mnemonic 
)

Read/write an entire sequence of data values from/to a data subset.

Wraps ufbseq() subroutine.

Parameters
bufr_unit- the Fortran logical unit number to read from.
c_data- pointer to a pointer to a pre-allocated buffer.
dim_1- dimensionality of data to read or write.
dim_2- dimensionality of data to read or write.
iret- return value, length of data read.
table_d_mnemonic- Table A or Table D mnemonic.
Author
J. Ator
Date
2023-04-07