Retrieving messages

The Retrieve Message (RTVMSG) command and retrieve message (QMHRTVM) application programming interface (API) have a CCSID-to-convert-to parameter. This parameter determines which CCSID the first- and second-level text is converted to before the text is returned to the user.

The Retrieve Message command and the Retrieve Message API also have a replacement data CCSID parameter. This parameter communicates the CCSID of the replacement data to the system. The replacement data CCSID applies only to the parts of the replacement data that correspond to *CCHAR type data. No other replacement data is converted.

The Retrieve Message command and Retrieve Message API convert the first- and second-level text from the CCSID of the message file to the CCSID on the CCSID-to convert-to parameter. Any replacement data that is *CCHAR data is converted from the replacement data CCSID to the CCSID-to-convert-to CCSID before being substituted into the correct replacement variables. The default for both parameters is *JOB, which means that the CCSID of the job is used.

Retrieve Message command CCSID return fields

Three CCSID return fields are supported by the Retrieve Message (RTVMSG) command:

TXTCCSID
TXTCCSTA
MDTACCSTA

Example 1: Retrieving a message with CCSID support

Message file MYMSGF has a CCSID of 65534. The CCSID of the message description is used to determine the CCSID from which to convert the message text. The CCSID of the message description (TST0003) is 00037. The first-level text is:

'MSG #3 is &1;'

&1 is defined as a *CCHAR variable field with a length of (*VARY 2). Enter the following RTVMSG (Retrieve Message) command:

RTVMSG MSGF(MYMSGF) MSGID(TST0003) MSG(&MSG); CCSID(277)  +
MDTACCSID(277) MSGDTA(X'0002D6D2')

In the message data, the first 2 bytes are a length field with a value of 2. All *VARY fields begin with a length. The next 2 characters are the actual *CCHAR data with a value of X'D6D2'. X'D6D2' represents the characters O and K on code page 00277.

The first-level text is converted from CCSID 00037 to CCSID 00277. The replacement data is not converted before it is substituted for &1; because the replacement data CCSID matches the CCSID-to-convert-to parameter. As a result, the text returned in the variable &MSG is:

'MSG #3 is OK.'

The code point for the number sign (#) is the only change that occurred in the conversion. The number sign was converted from code point X'7B' in code page 00037 to code point X'4A' in code page 00277. All other code points in the text of the message matched in code page 00037 and code page 00277.

Note: If the CCSID of a message file is 65535, no conversion occurs, even though the message description CCSID is 00037. The CCSID of the message file always takes precedence over the message description CCSID.

Example 2: Using return fields and converted character data

Message description TST0005 has the following first-level text:

This is *CHAR &1;  This is *CCHAR &2;

The message description is defined in message file MYMSGF, which has a CCSID of 65535. &1; is defined as a *CHAR field of length 1. &2; is defined as a *CCHAR field (*VARY 2) in length. The CCSID of the message description does not matter because the CCSID of the message file is not 65534. You enter the following RTVMSG command:

RTVMSG MSGF(MYMSGF) MSGID(TST0005) MSG(&MSG); CCSID(260)  +
MDTACCSID(37) MSGDTA(X'5A00015A') TXTCCSID(&TXTCCSID);

Note: X'5A' is the exclamation point (!) on code page 00037.

These are the returned values from the RTVMSG command:

&MSG = 'This is *CHAR. This is *CCHAR !.'
The EBCDIC value of the *CHAR character is X'5A'. X'5A' appears as an acute accent ( ) on code page 00260. The *CHAR data did not convert because only *CCHAR data supports CCSID processing. The '&1' stayed at X'5A', while '&2' converted to X'4F'. X'4F' is the exclamation point on code page 00260.
&TXTCCSID = 65535
The TXTCCSID variable is set to 65535 because no conversion occurred. When no conversion occurs, the CCSID (if it is not 65534) of the message file is returned.