Defining Language Messages

Installation Options › National Language Support › Defining Language Messages

Defining Language Messages

The next two sections contain information on defining messages for a national language. You should also be aware that CA ACF2 for z/VM provides the following default warning message:

After July 1, 1999 this access will not be allowed

To change the text of this message, you must change the MSG operand of the WARN VMO record. For information on changing this VMO record, see the Administrator Guide.

CA ACF2 for z/VM requires you define messages for a national language in separate modules. HCPAF0 is a required language module. As shipped, this module contains American English (AMENG). HCPAL0, another CA ACF2 for z/VM language module, contains Upper Case English (UCENG). We provide nine separate dummy modules for your use, HCPAL1 through HCPAL9. Use these modules to define a site‑generated language for CA ACF2 for z/VM.

You must define any additional national languages through the LANG operand of the VMXAOPTS macro in HCPAC0. This operand specifies each national language module and the text file where CA ACF2 for z/VM defines the message text for the language. The System Programmer's Guide contains complete information about defining your national languages through the LANG operand.

CA ACF2 for z/VM codes the language modules using the ACFCPMST, ACFMDEST, and ACFMSGEN macros. The Altering Message Attributes Through ACFCPMST and Generating the Message Table through ACFMSGEN sections explain each of these macros in detail.

Altering Message Attributes through ACFCPMST

The ACFCPMST macro defines each message. It always generates the text of a message. CA ACF2 for z/VM base language module (HCPAF0) only generates the attributes of a message. If an alternate language module defines attributes, CA ACF2 for z/VM validates but does not use them.

You can customize CA ACF2 for z/VM messages to meet your site's needs. For example, you can modify the messages that CA ACF2 for z/VM normally sends to the operator so that they are sent elsewhere. (This is an alternative to setting up the PROP message routing tables for CA ACF2 for z/VM messages.) Failure to modify the routing of messages when you are running PROP can result in performance problems.

You can modify a message's ACFCPMST macro to alter the text and attributes of any CA ACF2 for z/VM message.

ACFCPMST 242W,'ACFFDR mode is invalid ‑ mode set to abort',  X
      HILIGHT=YES,                                           X
      USER=NO,                                               X
      OPER=YES

The attributes specified in this macro indicate that CA ACF2 for z/VM highlights the message at the system operator's terminal.

You can customize this message for different results. The following changes send the message to a list of logonids in charge of implementing security (as opposed to the operator). We have also modified the message text.

ACFCPMST 242W,'ACFFDR mode is invalid ‑ mode set to abort ‑ sX
      ecurity team take action if necessary',                X
      HILIGHT=YES,                                           X
      USER=NO,                                               X
      DEST=secteam

The ACFAMENG copybook defines American English messages. There must be an entry for ACFAMENG in the ACF2USER EXEC. The ACFUCENG copybook defines Upper Case English messages. The ACFAMENG copybook contains the above message. We ship HCPAF0 using the ACFAMENG copybook and HCPAL0 using the ACFUCENG copy book.

You can use the following operands to customize CA ACF2 for z/VM messages.

ACF2SM=YES|NO

Specifies whether CA ACF2 for z/VM sends the message to the service machine console. NO is the default. CA ACF2 for z/VM only accepts YES if a CP module or the service machine issued the message.

ALARM=YES|NO

Specifies whether an audible alarm sounds at the destination. NO is the default. YES has no effect if CA ACF2 for z/VM returns the message in a buffer for a module running in CMS or GCS. This includes messages the ACF command, CA ACF2 for z/VM reports, and SRF issue. Messages that programs running in CMS issue respect the YES setting only if you set CMS FULLSCREEN on. It does not respect YES in line mode (a limitation of the CMS TERMWRT macro).

COMPRES=YES|NO

Specifies whether CA ACF2 for z/VM compresses multiple contiguous blanks into a single blank and removes all trailing blanks before display. YES is the default.

DEST=label

Defines a ACFMDEST macro label that defines a list of logonids where CA ACF2 for z/VM sends the message. Use DEST with the USER and OPER attributes. If the defined user is disconnected, CA ACF2 for z/VM does not display the message unless you use IUCV MSG. There is no default value. CA ACF2 for z/VM only respects this attribute if a CP module or the service machine issued it.

DISPLAY=EMSG|IMSG|FULL|NOID

Specifies how CA ACF2 for z/VM sends the message. EMSG indicates that the message is a CP EMSG (respects all EMSG settings). IMSG indicates that the message is a CP IMSG (respects all IMSG settings). FULL indicates that CA ACF2 for z/VM always displays the message ID and text, regardless of EMSG and IMSG settings. NOID indicates that CA ACF2 for z/VM displays only the message text, regardless of EMSG and IMSG settings. The default is EMSG.

If CA ACF2 for z/VM returns the message in a buffer for a module running in CMS or GCS (including command modules, reports, and SRF), it respects the user's EMSG setting unless you specify NOID, displaying the message text. Message programs running in CMS respect the NOID and FULL operands, otherwise CA ACF2 for z/VM outputs the message according to the EMSG setting.

HILIGHT=YES|NO

Specifies whether CA ACF2 for z/VM highlights the message at the destination terminal. NO is the default. YES has no effect if CA ACF2 for z/VM returns the message in a buffer for a module running in CMS or GCS. This includes messages the ACF command, CA ACF2 for z/VM reports, and SRF issue. Message programs running in CMS respect the YES setting only if you set CMS FULLSCREEN on. CA ACF2 for z/VM does not respect YES in line mode (a limitation of the CMS TERMWRT macro).

OPER=YES|NO

Specifies whether CA ACF2 for z/VM routes the message to the operator's console. NO is the default. CA ACF2 for z/VM respects YES only if a CP module or the service machine issued the message.

PRIOR=YES|NO

Specifies whether the message is a priority warning, immediately interrupting the user's virtual machine. NO is the default. YES has no effect if CA ACF2 for z/VM returns the message in a buffer for a module running in CMS or GCS. This includes messages the ACF command, CA ACF2 for z/VM reports, and SRF issue.

PRND=YES|NO

Sets the terminal input field to nondisplay. Used for password prompt messages, the YES setting prevents the display of any of the password between the time CA ACF2 for z/VM issues this message and the time that CA ACF2 for z/VM reads the password.

USER=YES|NO

Specifies whether CA ACF2 for z/VM routes the message to the user's terminal. YES is the default. CA ACF2 for z/VM respects NO only if a CP module or the service machine issued the message.

The following variables indicate substitutions in the message text:

&x1,...,&x9

CA ACF2 for z/VM substitutes data from the message request for the variable. The number denotes the relative position in the message request substitution list of the data that replaces the variable. x specifies the format of the data. CA ACF2 for z/VM uses this information to convert data to a readable format in the message. Valid values for x are:

&C-: Character format
&D: Decimal data (binary converted to decimal)
&H: Hexadecimal data
&T: Character standard CMS tokenized data in character format.

Below are examples of using these variables in messages:

Invalid data &C1 in field &C2 in record &D3

Record &D3, field &C2, has invalid data &C1

File &T1 not found, FSOPEN RC=&D2

Program &C1 loaded at address &H2

&DATE

The current date

&LID

The VM user ID of the logged on user

&SMFID

The SMFID parameter value of the ACFFDR @SMF macro

&TIME

The current time

&UID

The UID of the logged on user (CA ACF2 for z/VM does not substitute this variable during a NOAUTO IPL)

&USERID

The VM user ID of the logged on user.

You must enter all the above variables in upper case, as shown. A message without any ACFCPMST macro operands assumes the defaults.

We recommend the following step‑by‑step procedure for altering message text:

Use XEDIT with the CTL option to update the copy book containing the ACFCPMST macros for your messages (for example:
```
XEDIT ACFAMENG COPY (CTL ACF2)
```
ACFAMENG is the copybook containing CA ACF2 for z/VM messages in mixed case American English. HCPAF0 uses this copybook. Alter the ACFCPMST macro attributes for the messages you want to change.
Use XEDIT to insert the following line into the ACF2USER EXEC file:
```
&1 &2 &3 ACFAMENG COPY *
```
Use VMFMAC to rebuild the ACF2USER maclib as follows:
```
VMFMAC ACF2USER ACF2
```
Copy ACF2USER MACLIB to the local options disk (2A0) and erase it from the A‑disk.
Reassemble the HCPAF0 message module.
```
VMFHASM HCPAF0 ppfname component
```
ppfname

The name of your PPF file used for genning CP

component

The component ID, normally CPTEST.

Note: If you use the high level assembler, then use VMFHLASM instead of VMFHASM.
Regenerate CP.

Defining User IDs through ACFMDEST

The ACFMDEST macro defines a list of user IDs. One or more ACFCPMST macros can specify the label of an ACFMDEST macro to route messages to users defined in the list. This macro is valid only in the CA ACF2 for z/VM base language module, HCPAF0.

Generating the Message Table through ACFMSGEN

The ACFMSGEN macro generates a message reference table and defines the substitution characters CA ACF2 for z/VM uses in the message defined in this module. The default is an ampersand (&).

The ACFNLANG macro defined in the base language module references the entry point for this table. This must be the last macro defined in the message module.