MVS Message Service (MMS) Exits

Topics for This Exit Appear as Follows:

Installing the Exit Routines
Exit Routine Environment
- Exit Recovery
Exit Routine Processing
- Message Translation
- Language Query
Programming Considerations
- Macro Instructions and Restrictions
Entry Specifications
- Registers at Entry
- Parameter Descriptions
Return Specifications
- Registers at Exit
Coded Examples of MMS Exit Routines
- MMSEXIT1: Preventing Translations of a Particular Language
- MMSEXIT2: Collecting MMS Usage Statistics

The MVS™ message service (MMS) enables you to translate U.S. English messages into other languages.

If you are routing system messages to a TSO/E extended MCS console, TSO/E will display translated messages in the primary language associated with the TSO/E session. If MMS is active, users of extended MCS consoles on TSO/E can select available languages for message translation and the system can display translated messages on the user's screen. TSO/E terminal users can also receive on their terminals translated TSO/E messages and the translated messages of any application that directs its messages to TSO/E and uses MMS services directly or through TSO/E services. To receive translated messages on TSO/E terminals, you must have TSO/E Version 2.2 installed on your system.

MMS provides two installation exit points that allow you to modify MMS processing. The MMS exits are invoked when application programs issue macros to request the following user functions:

Message translation
Language query (to see if a particular language is available).

For information on MMS and MMS user functions, see z/OS MVS Programming: Assembler Services Guide.

For information on MMS macros, see z/OS MVS Programming: Assembler Services Reference ABE-HSP.

There are two MMS exits: the MMS preprocessing exit and the MMS postprocessing exit. The MMS preprocessing exit is invoked before MMS processes the user function. The MMS postprocessing exit is invoked after MMS processes the user function.

The MMS preprocessing exit can be used to:

Replace existing translations of selected messages with other installation-defined translations.
Prevent translation of selected messages.
Set a local communication word that will be passed to the MMS postprocessing exit. Use this field to pass any information to your postprocessing exit.

The MMS postprocessing exit can be used to:

Collect MMS usage statistics.

Installing the Exit Routines

The MMS exits must reside in an APF-authorized load library included in the LNKLST concatenation.

Statements that identify either an MMS preprocessing exit routine, an MMS postprocessing exit routine, or both, must be specified in the appropriate MMSLSTxx member of SYS1.PARMLIB.

In MMSLSTxx, do the following on an EXIT statement:

On the NUMBER keyword:
- To identify an MMS preprocessing exit, specify: (1)
- To identify an MMS postprocessing exit, specify: (2).
Specify the module name of the exit routine on the ROUTINE parameter.

For example, to identify both an MMS preprocessing exit (MMSEXIT1) and an MMS postprocessing exit (MMSEXIT2) in an MMSLSTxx parmlib member, specify:

           EXIT NUMBER(1)  ROUTINE(mmsexit1)
           EXIT NUMBER(2)  ROUTINE(mmsexit2)

No more than two MMS exit routines can be specified in an MMSLSTxx parmlib member.

For more information on the MMSLSTxx parmlib member, see z/OS MVS Initialization and Tuning Reference.

For general instructions on installing an exit routine, see Link editing an Installation Exit Routine into a Library.

Replacing the Exit Routines: To replace an MMS exit routine when MMS is active, you must either:

Modify the MMSLSTxx parmlib member to name a different exit routine on the ROUTINE parameter and issue the SET MMS=xx command to refresh the parmlib member.
Issue the SET MMS=xx command for the MMSLSTxx parmlib member that names the required MMS exit routine.

For more information on the SET MMS command, see z/OS MVS System Commands.

Exit Routine Environment

The exit routines receive control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In AMODE 31 and RMODE ANY.
In the MMS address space.
In pageable storage.
In cross memory mode.

Exit Recovery: MMS provides a functional recovery routine (FRR) to protect the exits.

If the MMS exit routine abends, the system will shut down MMS. The system recovery routine will request an SDUMP that can be used by the installation to debug the exit routine.

Exit Routine Processing

The MMS preprocessing exit routine, if one is defined, is invoked before MMS processes the input parameter block (and its related data areas). The MMS postprocessing exit is invoked immediately after MMS processes the input parameter block but before the block has been copied back to the caller's address space.

The system passes the address of the input parameter block to the exits in word 1 of the exit routine parameter list (pointed to by register 1). For message translation, the input parameter block is a message input/output block (MIO), which is mapped by the CNLMMIO macro. For a language query, the input parameter block is a language query block (LQB), which is mapped by the CNLMLQB macro. The exit routines can modify these blocks as needed.

If your installation defines MMS exits, MMS will invoke the exits for both the message translation and language query functions. The system indicates the type of function for which the exit has been invoked in register 0 with one of the following codes:

Code: Meaning
1: Message translation
4: Language query

Message Translation: The MMS exits are invoked each time an application invokes MMS with a request to translate a message (register 0 is set to function code 1). If you code MMS exit routines to modify MMS translation, you will probably modify translations of selected messages. For the majority of MMS translations, the exit routines will allow the translations to occur without modification (as if the exit routines did not exist).

Allowing MMS Translations to Occur: To allow MMS translation of a message to occur, the exit routines simply return control to the system:

Without resetting the default of zero that is in the exit processing indicator (pointed to in word 3 of the parameter list)
With a zero return code in register 15.

The installation application receives the MMS translated message text.

Modifying MMS Translations: When you want to modify MMS translations, use the preprocessing exit routine. The MMS preprocessing exit is invoked before MMS translates a message. The exit routine can examine the input message text (pointed to by the MIO control block) and do one of the following:

Replace the message with installation-preferred message text
Prevent the message from being translated.

Using the Preprocessing Exit: To replace or prevent MMS translations of selected messages, code the preprocessing exit routine to set the exit processing indicator to a nonzero value and do one of the following:

Place an installation-defined message in the message output area (also pointed to in the MIO) and return control to the system. The installation-defined message is returned to the application that invoked MMS.
Return control to the system, thus preventing translation. The original, U.S. English form of the message is returned to the application that invoked MMS.
Set register 15 to a nonzero value and return control to MMS. The translation request will be terminated.

The exit routine must return a zero return code in register 15. Otherwise, MMS will terminate the translation request.

With one exception, the postprocessing exit routine (if one is defined) will be invoked even when MMS translation is bypassed. The exception is when the preprocessing exit routine indicates an error (by placing a value greater than 8 in a fullword pointed to by word 4 of the exit parameter list). See Return Specifications (Using Words 4 and 5) for more information.

Using the Postprocessing Exit: The MMS postprocessing exit (if one is defined) is invoked after MMS has translated a message, but before the message is returned to the end user.

Like the MMS preprocessing exit routine, the MMS postprocessing exit routine can examine the input message parameters and place installation-preferred message text in the message output area. Because it is invoked after MMS message translation has occurred, the MMS postprocessing exit routine cannot bypass MMS processing. However, the postprocessing exit routine can do one of the following:

Gather statistics
Set the exit processing indicator to a nonzero value and return control to MMS. The original, U.S. English form of the message is returned to the application.

Language Query: The MMS exits are invoked when MMS receives a query to determine which languages are available for message translation (register 0 is set to function code 4).

When invoked during a language query, an MMS exit could:

Collect usage statistics
Modify the list of languages to be returned to the application (in the LQB).

Programming Considerations

Using Information in the Exit Parameter List:

The system passes the address of the input parameter block to the exits in word 1 of the exit routine parameter list (pointed to by register 1). For message translation, the input parameter block is a message input/output block (MIO). For a language query, the input parameter block is a language query block (LQB). The exit routines can modify these blocks as needed. For the mappings of the MIO and LQB control blocks, see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.
The system passes to the exit routines the address of a local communication word in word 2 of the exit parameter list. The pre and postprocessing exit routines can use the local communication word to share data (or the address of data) for one user invocation of MMS.
The system provides the address of the exit processing indicator in word 3 of the exit parameter list. An MMS exit routine can cause MMS processing of a particular message to be bypassed by setting the exit processing indicator to a nonzero value. The exit processing indicator is set to 0 each time MMS invokes the exit.
The exit routines can indicate processing errors by placing installation-defined return and reason codes in areas pointed to by words 4 and 5, respectively, of the exit routine parameter list. See Return Specifications (Using Words 4 and 5) for more information.
The system passes to the exit routines the address of a 512-byte work area in word 6 of the exit routine parameter list. The exits can use the work area for the current invocation of the service. Additional storage, if required, must be obtained by the exit routines by issuing a STORAGE or branch-entry GETMAIN macro.

Other Considerations:

Code the exit routines to be reentrant.
Because the exit routines run in cross memory mode, they cannot issue SVCs.
The exit routines are invoked each time MMS processes the message translate or language query functions. Therefore, when coding the exit routines, you should be aware that an increased path length will increase processor use and affect performance.
The exit routines must follow standard linkage conventions.

Macro Instructions and Restrictions: The exit routines can only use services that run in cross-memory mode. See z/OS MVS Programming: Assembler Services Reference ABE-HSP for information on services that run in cross-memory mode.

Entry Specifications

MMS passes to the exit the address of the input parameter block (either an MIO or an LQB, depending on the type of request that MMS has been called to process).

Registers at Entry: The contents of the registers on entry to the MMS exit routines are:

Register: Contents
0: Type of MMS function the installation application requested (1 for message translation, 4 for language query)
1: Address of the exit parameter list
2-12: Undefined
13: Address of an 18-fullword register save area
14: Return address
15: Entry point address of exit

Parameter Descriptions: Register 1 points to the following list of addresses:

Word 1

The address of an MIO or LQB control block.

When the exit is invoked for the message translation function, this field will point to the address of an MIO (mapped by macro CNLMMIO).
When the exit is invoked for the language query function, this field will point to the address of an LQB (mapped by macro CNLMLQB).

Word 2

The address of a local communication word.

Word 3

The address of the exit processing indicator. The indicator is set to 0 by default.

Word 4

The address of an optional, installation-defined return code.

Word 5

The address of an optional, installation-defined reason code.

Word 6

The address of a 512-byte storage area (starting on a double-word boundary) that the exit routines can use for the current invocation of MMS.

Return Specifications

The exit routines return control to the system with:

A value in the exit processing indicator, pointed to by Word 3 of the exit parameter list.
Optional, installation-defined return and reason codes, pointed to by words 4 and 5 of the exit parameter list.
A return code in register 15.

Preprocessing Exit Routine: The exit routine indicates whether to bypass the requested MMS function by setting the exit processing indicator to a nonzero value. If the exit processing indicator is not set, the system will process the function.

Using Words 4 and 5: The preprocessing exit routine can return optional, installation-defined return and reason codes in areas pointed to by words 4 and 5, respectively, of the exit parameter list. When the exit routine sets the exit processing indicator to a nonzero value, the system checks the value in the area pointed to by word 4. The exit routine can indicate that it has encountered a serious error by setting the field pointed to by word 4 to a value greater than 8. When this happens, MMS terminates the user request. Otherwise, if the field pointed to by word 4 is set to a value of 8 or less, or the exit routine does not set the exit processing indicator, MMS continues processing and the fields pointed to by words 4 and 5 are passed as information to the MMS postprocessing exit routine (if one is defined).

Postprocessing Exit Routine: Like the preprocessing exit routine, the postprocessing exit routine can cause MMS processing to be bypassed by setting the exit processing indicator to a nonzero value and returning control to the system with a zero return code in register 15. However, any values the exit routine places in the fields pointed to by words 4 and 5 of the exit parameter list are not used by the system.

Registers at Exit: Upon return from exit routine processing, the register contents must be:

Register

Contents

0,1

Undefined

2-14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
0: The exit routine has completed processing.
nonzero: The exit routine has encountered an error. MMS will terminate the user request.

Coded Examples of MMS Exit Routines

This topic contains the following sample MMS exit routines:

MMSEXIT1. This MMS preprocessing exit routine prevents translation of a particular language.
MMSEXIT2. This MMS postprocessing exit routine collects MMS usage statistics.

MMSEXIT1 -- Preventing Translations of a Particular Language: In the following example, an installation uses the MMS preprocessing exit routine to prevent MMS from translating messages into Japanese.

The installation places the language code of the language for which translations are to be suppressed (in this case, JPN is the language code) into the CVTUSER field of the CVT so that the exit routine can access it.

When the installation's exit routine is invoked for a translation request, the routine compares the language code in the CVTUSER field with the language code contained in the MIO. When the request is for Japanese translation (MIO contains 'JPN'), the exit routine causes MMS translation to be bypassed by setting the exit processing indicator (pointed to by word 3 of the exit parameter list) to a nonzero value and returning control.

MMSEXIT1 CSECT
MMSEXIT1 AMODE  31
MMSEXIT1 RMODE  ANY
         STM    14,12,12(13)
         BALR   12,0
         USING  *,12
***********************************************************************
***                                                                   *
***     FOR A TRANSLATION REQUEST, THIS EXIT WILL COMPARE THE         *
***     LANGUAGE CODE CONTAINED IN THE CVTUSER FIELD OF THE CVT       *
***     WITH THAT CONTAINED IN THE MIO FOR THIS REQUEST. THIS EXIT    *
***     ASSUMES THE INSTALLATION HAS UPDATED THE CVTUSER FIELD TO     *
***     CONTAIN THE DESIRED THREE CHARACTER LANGUAGE CODE. IF THE     *
***     LANGUAGE CODE CONTAINED IN THE CVTUSER FIELD MATCHES THE      *
***     CODE IN THE MIO, THE TRANSLATION REQUEST WILL BE              *
***     TERMINATED BY SETTING THE EXIT PROCESSING INDICATOR           *
***     TO A NON-ZERO VALUE.                                          *
***                                                                   *
***                                                                   *
***********************************************************************
*

         C     R0,ONE                             TRANSLATION REQUEST?
         BNE   END                                NO, END PROCESSING
         L     R3,0(,R1)                          OBTAIN MIO ADDRESS
         L     R2,16(0,R0)                        OBTAIN CVT ADDRESS
         CLC   CVTUSER-CVT(3,R2),MIOLANG-MIO(R3)  COMPARE LANG. CODES
         BNE   END                                EXIT IF NOT EQUAL
         L     R3,8(,R1)                          OBTAIN PROCESSING    C
                                                    INDICATOR ADDRESS  C
         MVC   0(4,R3),ONE                        SET PROCESS          C
                                                   INDICATOR TO        C
                                                   PREVENT TRANSLATION C
END      DS    0H
         LM    14,12,12(13)
         SLR   15,15
         BR    14
***********************************************************************
ONE      DC    F'1'
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
***********************************************************************
         DSECT
         CVT   DSECT=YES
         CNLMMIO
         END MMSEXIT1

MMSEXIT2 -- Collecting MMS Usage Statistics: In the following example, an installation uses the MMS postprocessing exit routine to track the number of successful and unsuccessful (successful=RC0, unsuccessful=nonzero) translations of U.S. English into Japanese.

The installation first creates a work area to contain counters of successful and unsuccessful translations. The routine places the address of the work area in the CVTUSER field of the CVT so that the postprocessing exit routine can find the work area and update the counters.

The installation can use the following MMS postprocessing exit routine to determine whether the translation was successful. Based on the result, the routine updates the appropriate counter in the work area (pointed to in CVTUSER).

MMSEXIT2 CSECT
MMSEXIT2 AMODE  31
MMSEXIT2 RMODE  ANY
         STM    14,12,12(13)
         BALR   12,0
         USING  *,12

***********************************************************************
***     FOR A TRANSLATION REQUEST, THIS EXIT ROUTINE WILL OBTAIN      *
***     THE ADDRESS OF AN INSTALLATION DEFINED CONTROL BLOCK          *
***     (POINTED TO BY THE CVTUSER FIELD OF THE CVT CONTROL BLOCK).   *
***     IF THE INSTALLATION CONTROL BLOCK EXISTS,                     *
***     A CHECK OF THE SUCCESS OR FAILURE OF THE TRANSLATION          *
***     REQUEST WILL BE MADE AND THE APPROPRIATE SUCCESS/FAILURE      *
***     COUNTER IN THE INSTALLATION CONTROL BLOCK WILL BE UPDATED.    *
***********************************************************************
         C     R0,ONE                       TRANSLATION REQUEST?
         BNE   END                          NO, END PROCESSING
         L     R2,0(,R1)                    OBTAIN MIO ADDRESS
         CLC   MIOLANG-MIO(3,R2),=C'JPN'    COMPARE LANGUAGE           C
                                                      CODES
         BNE   END                          EXIT IF NOT EQUAL
         L     R2,0(,R0)
         L     R3,CVTUSER-CVT(,R2)          OBTAIN INSTALLATION        C
                                              CONTROL BLOCK ANCHOR
         LTR   R3,R3                        INSTALLATION CONTROL BLOCK C
                                             PRESENT?
         BZ    END                          NO,END
         L     R4,12(,R1)                   OBTAIN RETURN CODE ADDRESS
         L     R4,0(,R4)                    OBTAIN RETURN CODE
         LTR   R4,R4                        TEST RETURN CODE
         BNZ   FAIL
         L     R5,INSTLSUC-INSTLCB(R3)      OBTAIN SUCCESS COUNTER
         LA    R5,1(,R5)                    BUMP COUNTER
         ST    R5,INSTLSUC-INSTLCB(R3)      SAVE COUNTER
         B     END                          GOTO END
FAIL     L     R5,INSTLFAL-INSTLCB(R3)      OBTAIN FAILURE COUNTER
         LA    R5,1(,R5)                    BUMP COUNTER
         ST    R5,INSTLFAL-INSTLCB(R3)      SAVE COUNTER
END      DS    0H                           RETURN
         LM    14,12,12(13)
         SLR   15,15
         BR    14
***********************************************************************
ONE      DC    F'1'
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
***********************************************************************
         DSECT
         CVT   DSECT=YES
         CNLMMIO
INSTLCB  DSECT               INSTALLATION CONTROL BLOCK
INSTLACR DS    CL4'INST'     INSTALLATION CONTROL BLOCK ACRONYM
INSTLSUC DS    F             LANGUAGE USAGE COUNTER FOR JAPANESE       C
                               SUCCESSFUL TRANSLATIONS
INSTLFAL DS    F             LANGUAGE USAGE COUNTER FOR JAPANESE       C
                               UNSUCCESSFUL TRANSLATIONS
         DS    CL12          RESERVED
INSTLLEN EQU   *-INSTLCB
         END MMSEXIT2