Retrieve MSGID Info from *MSGF Object (RTVMSGD and RTVMSGID) UDTF




MSGF => 'message-file-name',
MSGID => '*FIRST' | 'msgid',
MSGID_CTL => '*MSGID' | '*NEXT' | '*GE' )


RTVMSGID( MSGID => '*FIRST' | 'msgid', 
MSGF => 'message-file-name',
MSGID_CTL => '*MSGID' | '*NEXT' | '*GE' )

The Retrieve Message Description (RTVMSGD) User Defined Table Function returns one row containing the Message ID, severity, and the 1st and 2nd level message text.

The Retrieve Message ID (RTVMSGID) UDTF is functionally the same as the RTVMSGD UDTF except the parameter list is different. They can be used interchangeably but RTVMSGID calls RTVMSGD to retrieve the MSG info.

The MSGID parameter along with the optional MSGID_CTL parameter controls which message ID's information is returned.
The RTVMSGD UDTF provide an alternative to using the QMHRTVM API but does not provide the extensive results of that API since that info is rarely needed in production application development. Use this UDTF to dynamically retrieve the 1st level message text for a message ID, quickly. For example, to retrieve the message text for CPF2101 using the RTVMSGID UDTF::




The library name of the object. If unspecified, *LIBL is used.


The name of the *MSGF object that contains the MSGID. If this parameter is not specified, QCPFMSG is used.


The 7-character Message ID of the message to be retrieved, or *FIRST to return the first message in the file. Note the actual message ID retrieve is returned in the MSGID column of the resultSet table.

MSGID_CTL (Message ID Search Control)

This parameter controls whether the actual message ID specified on the MSGID parameter is returned (MSGID_CTL=>'*MSGID') or if the next message in the message file is returned (MSGID_CTL=>'*NEXT').
This option allows users to call the UDTF with a message id, such as CPF2100 and specify MSGID_CTL=>'*NEXT' and have it return the description for CPF2101 description.
This capability, combined with MSGID=*FIRST can be used to iterate through the list of message IDs in a message file (in an RPG program or iQuery script).
Remember that message IDs consist of 3 characters followed by 4 hexadecimal values. Originally (back in the 1980s) msg IDs were XXX9999 where 9999 are digits 0000 through 9999. Today in order to expand the number of available message IDs, the last 4 positions of the msg ID have become hexadecimal values. So 0 to 9 and A to F are supported. However, messages are "sorted" as character data, so CPF210F appears before CPF2101 in the result set.


dcl-s msgText varchar(132);
dcl-s severity int(10);

exec SQL select msg_text INTO :msgText
FROM TABLE( iQuery.RTVMSGD( msgf=>'QCPFMSG', msgid=>'CPF21B5')) msg;

exec SQL Select msg_text,severity INTO :msgText, :severity
FROM TABLE( iQuery.RTVMSGID( 'CPF21B5') ) msg;
These examples retrieve message ID CPF21B5 from the QCPFMSG message file. The first one stores the resulting 1st level message text into the MSGTEXT RPG variable. The 2nd statement does the same thing but also returns the Message Serverity in the SEVERITY RPG variable.

Column Data Type Description
The name of the library where the MSGF (message file) is located. If *LIBL or *CURLIB is used on the LIBRARY_NAME parameter or if LIBRARY_NAME is omitted, this column will receive the library name where the message file was located by the UDTF.
VARCHAR(10) The name of the message file.
CHAR(7) The message ID being returned. This will match the MSGID input parameter unless *NEXT or *GE are specified for MSGID_CTL
The severity code of the message. Message severity is from 0 to 99.
MSG_TEXT VARCHAR(132) The first-level message text for the message ID. Up to 132 characters are returned. CCSID 1200 is used, but it should map into CCSID EBCDIC 37 just fine.
The second level message text for the message file. Up to 3000 characters are returned.  CCSID 1200 is used, but it should map into CCSID EBCDIC 37 just fine.