Retrieving translated messages (TRANMSG macro)

TRANMSG takes the application messages that you provide, and retrieves the corresponding translated messages from the system run-time message files. TRANMSG returns the translated message in a message text block (MTB).

If the requested language is not available, TRANMSG returns the message unchanged. To check the availability of specific languages, use the QRYLANG macro described in Determining which languages are available (QRYLANG macro).

In your application, call TRANMSG as close to the point of message presentation as possible to avoid presenting a translated version of the message to MVS™ functions (for example, installation exits, automation CLISTs, MCS consoles) that expect English text.

A message input/output block (MIO), mapped by CNLMMIO, serves as both input to and output from TRANMSG. You can either build the MIO yourself or have TRANMSG do it for you. If you do not supply a formatted MIO, TRANMSG constructs one by using the information you supply through the macro parameters. Build the MIO yourself if you are translating multi-line messages that have continuation lines. You will need to set the MIOCONT flag in the MIO.

If you build the MIO yourself, the MIO must contain the following when you issue TRANMSG:

The code of the language into which you want the message translated
The addresses of the messages you want translated
The address of an output buffer in the calling program's address space where TRANMSG is to return the translated message or messages.

For a mapping of the MIO, see z/OS MVS Data Areas in the z/OS Internet library.

The application's input messages can be in one of the following forms:

Message text blocks (MTBs, mapped by CNLMMTB)
Message parameter blocks (MPBs, mapped by CNLMMPB)
Self-defined text (a 2-byte length field followed by message text)
A combination of any of the three.

When TRANMSG completes, the MIO contains the address of the translated message in the output buffer. The translated message is in the form of an MTB.

Translating a multi-line message is a little different from translating a single-line message. You must take one of the following steps in preparing the multi-line message for translation:

Add the message identifier to the beginning of the message text for each line subsequent to the first. You can invoke TRANMSG once for all message lines, or once for each message line. For the example above, the modified message would appear as follows:
```
MSGID01 THIS IS LINE ONE OF THIS MULTI-LINE MESSAGE
MSGID01 THIS IS LINE TWO OF THIS MULTI-LINE MESSAGE
MSGID01 THIS IS LINE THREE OF THIS MULTI-LINE MESSAGE
```
When you invoke TRANMSG, MMS will process this message as three separate lines of text.
Set the MIOCONT flag on the MIO message entry structure for lines subsequent to the first (lines two and three in the following example). The MIOCONT flag informs MMS that a specific line of text is associated with the previous line of text. MMS associates the message identifier of the first line with the message text of the subsequent lines. z/OS MVS Programming: Assembler Services Reference IAR-XCT provides a coding example that translates a multi-line message.
The following is an example of a multi-line message that contains continuation lines, that is, only the first line contains a message identifier in the skeleton. You must include all lines in the TRANMSG invocation.
```
MSGID01 THIS IS LINE ONE OF THIS MULTI-LINE MESSAGE
        THIS IS LINE TWO OF THIS MULTI-LINE MESSAGE
        THIS IS LINE THREE OF THIS MULTI-LINE MESSAGE
```

Figure 1 shows how an application program uses the TRANMSG macro.

Figure 1. Using the TRANMSG Macro