Decode the meaning of a numerical value from a code or flag table. More...

Functions/Subroutines
subroutine	getcfmng (LUNIT, NEMOI, IVALI, NEMOD, IVALD, CMEANG, LNMNG, IRET)
	This subroutine searches for a specified Table B mnemonic and associated value (code figure or bit number) within the master Code/Flag tables, and if found returns the associated meaning as a character string. More...

Detailed Description

Decode the meaning of a numerical value from a code or flag table.

Definition in file getcfmng.f.

Function/Subroutine Documentation

subroutine getcfmng	(		LUNIT,
		character()	NEMOI,
			IVALI,
		character()	NEMOD,
			IVALD,
		character()	CMEANG,
			LNMNG,
			IRET
	)

This subroutine searches for a specified Table B mnemonic and associated value (code figure or bit number) within the master Code/Flag tables, and if found returns the associated meaning as a character string.

Author: J. Ator

Date: 2018-01-11

Parameters

[in]	LUNIT	- integer: Fortran logical unit number for BUFR file
[in]	NEMOI	- character(): Mnemonic to search for
[in]	IVALI	- integer: Value (code figure or bit number) associated with NEMOI
[in]	NEMOD	- character(): Optional second mnemonic upon which the values NEMOI and IVALI depend; set to all blank characters if the meanings of NEMOI and IVALI do not depend on the value of any other mnemonic
[in]	IVALD	- integer: Value (code figure or bit number) associated with NEMOD; set to (-1) whenever NEMOD is set to all blank characters
[out]	CMEANG	- character(): If the initial search of the master Code/Flag tables was successful, then this string contains the meaning corresponding to NEMOI and IVALI (and to NEMOD and IVALD, if specified). However, if the initial search was unsuccessful, and if no optional second mnemonic and associated value were specified on input, and if a second search of the table determines that the meaning of NEMOI and IVALI indeed depends on one or more other possible second mnemonics, then those possible second series of IRET successive 8-byte substrings. An example of this scenario is included below within the Remarks.
[out]	LNMNG	- integer: Length (in bytes) of string returned in CMEANG
[out]	IRET	- integer: return code 0 = meaning found and stored in CMEANG string -1 = meaning not found >0 = meaning not found, and NEMOD and IVALD were not specified on input, and the meaning of NEMOI and IVALI depends on the value of one of the mnemonics stored in the first IRET 8-byte substrings of CMEANG

As noted above, this subroutine first does an initial search of the master Code/Flag tables based on the mnemonics and values provided. The input parameters NEMOI and IVALI specify the mnemonic and corresponding numerical code or flag table value for which the meaning is sought, and the optional secondary parameters NEMOD and IVALD are specified when needed to differentiate between multiple possible results. An example of this particular scenario is included below within the Remarks. Otherwise, if the meaning of NEMOD and IVALD does not depend on the value associated with any other mnemonic, then NEMOD should be set to a field of all blank characters, and IVALD should be set to a value of (-1).

Subroutine codflg() must be called with a CF value of 'Y' prior to calling this subroutine, in order to ensure that master Code/Flag tables have been read into internal memory.

This subroutine can be called at any time after a BUFR message has been read into internal arrays by one of the BUFRLIB message-reading subroutines, and it can be called for any code or flag table mnemonic defined within that particular message. In most cases, this means that the mnemonic must be contained within the subset definition (Section 3) of that message. The only exceptions to this rule are for originating centers, originating subcenters, data types and data subtypes, since those can also be contained within the identification section (Section 1) of a BUFR message.

It is the user's responsibility to provide sufficient allocated space in CMEANG for the returned meaning string; otherwise, the returned string will be truncated.

Remarks

An example of when secondary mnemonics NEMOD and IVALD would be required is when a user is searching for the meaning of a numerical code table value for an originating sub-center (i.e. mnemonic GSES). The meaning of any originating sub-center value depends on the identity of the originating center for which the sub-center in question is a member, so in order for the subroutine to locate and return the proper one, information about the originating center must also be provided. So in this case the user would input GSES and the associated numerical value as NEMOI and IVALI, respectively, but the user would also need to specify an appropriate originating center mnemonic (e.g. GCLONG, OGCE or ORIGC) and associated value from the same BUFR message as input parameters NEMOD and IVALD, respectively, and then the subroutine will be able to locate and return the appropriate meaning string. Otherwise, if this information was not provided, the subroutine would return with an IRET value of 3, and with each of the mnemonics GCLONG, OGCE and ORIGC contained in successive 8-byte substrings of CMEANG (and with a corresponding value of 24 returned for LNMNG), as a hint to the user that more information needs to be input to the subroutine in order to achieve the desired result.

Program history log:

2018-01-11 J. Ator – Original author
2018-02-08 J. Ator – Add special handling for data types and subtypes in Section 1

Definition at line 108 of file getcfmng.f.

References bort(), ifxy(), ireadmt(), nemtab(), numtbd(), parstr(), srchtbf(), and status().

Referenced by fdebufr().

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation