Item translation

Allows you to translate an internal variable value to a displayed value (or vice-versa) on an item-for-item basis. To specify this translation, either code FORMAT=NONE on the XLATL tag or omit the FORMAT attribute because this is the default. You define the list of possible internal values and the corresponding display values they should be translated to, or from, using the XLATI (translate item) tags nested within the XLATL tag.

To specify an internal value (the value in the variable pool) for a translate item, use the VALUE attribute on the XLATI tag. The XLATI tag text specifies what the user sees (for output) and enters (for input).

The display value is the XLATI tag text. If a display value of all blanks or a display value in which leading, trailing, or embedded blanks are preserved is desired, use the literal (LIT) tag and its required end tag to indicate that blanks are significant.

An explicit match is achieved during translation processing as follows:

On input, an explicit match occurs when the value the user enters matches one of the specified display values in the translate list. An explicit match also occurs when a display value is omitted (indicating any value is acceptable) and the corresponding internal value is specified.
On output, an explicit match occurs when the value from the variable pool matches one of the specified internal values in the translate list. An explicit match also occurs when an internal value is omitted (indicating any value is acceptable) and the corresponding display value is specified.

Omitting both the internal value and the display value does not produce an explicit match. This case is discussed further on in this topic.

Translate list processing is case-sensitive. To ensure that a match results when the user enters the correct display value but in a different or mixed case, code an uppercase conversion translate list before the value translate list.

Here is an example where the variable class dayc uses an internal value for days of the week that is different from the display value. The comparisons are on uppercase values, because FORMAT=UPPER is provided before the item translation list.

<!doctype dm system>

<varclass name=dayc type='CHAR 9'>
  <xlatl format=upper>
  </xlatl>
  <xlatl msg=liba004>
    <xlati value=1>SUNDAY
    <xlati value=2>MONDAY
    <xlati value=3>TUESDAY
    <xlati value=4>WEDNESDAY
    <xlati value=5>THURSDAY
    <xlati value=6>FRIDAY
    <xlati value=7>SATURDAY
  </xlatl>

This figure shows how variable values of variable class dayc are translated on input and output.

Figure 1. Variable translation

On input, a user-entered value of "Wednesday" translates to an internal value of "4". On output, an internal value of "7" translates to "SATURDAY".

The previous example shows one translate list with a finite number of translation items. This example assumes that the only possible internal values are 1-7 and the only possible display values are the days of the week. For input fields, a match must be found in this list, or the translation fails and message liba004 is displayed to the user.

Here is an example which allows allow a nonmatching value to be passed on for further processing (either to another translate list or to the validity checks that follow) by coding an XLATI tag without an internal value or a display value, to indicate that any value is acceptable:

<!doctype dm system>

<varclass name=dayc type='CHAR 9'>
  <xlatl format=upper>
  </xlatl>
  <xlatl>
    <xlati value=1>SUNDAY
    <xlati value=2>MONDAY
    <xlati value=3>TUESDAY
    <xlati value=4>WEDNESDAY
    <xlati value=5>THURSDAY
    <xlati value=6>FRIDAY
    <xlati value=7>SATURDAY
    <xlati>
  </xlatl>

Because multiple translate lists are permitted, we can expand this example to accept either the days of the week spelled out or their accepted abbreviations. Because the last XLATI tag in the first translate list has no internal or displayed value, the input value are passed on for further translate list or validity checking.

<!doctype dm system>

<varclass name=dayc type='CHAR 9'>
  <xlatl format=upper>
  </xlatl>
  <xlatl>
    <xlati value=1>SUNDAY
    <xlati value=2>MONDAY
    <xlati value=3>TUESDAY
    <xlati value=4>WEDNESDAY
    <xlati value=5>THURSDAY
    <xlati value=6>FRIDAY
    <xlati value=7>SATURDAY
    <xlati>
  </xlatl>
  <xlatl>
    <xlati value=1>SUN
    <xlati value=2>MON
    <xlati value=3>TUES
    <xlati value=4>WED
    <xlati value=5>THUR
    <xlati value=6>FRI
    <xlati value=7>SAT
  </xlatl>

It is possible to omit only the internal value to indicate that any internal value is acceptable. This affects input and output translate processing differently. When translating on input, the value is not translated before being stored in the variable pool. When translating on output, any value not already matched is translated to the displayed value.

In the following example, the branchc variable class illustrates translate processing when only the internal value is omitted.

<!doctype dm system>

<varclass name=branchc type='CHAR 3'>
  <xlatl format=upper>
  </xlatl>
  <xlatl>
    <xlati value=1>RAL
    <xlati>CRY
  </xlatl>

Figure 2. Variable translation

On input, the user-entered value of "CRY" translates to the internal value of "CRY". On output, the internal value of "7" translates to the displayed value of "CRY".

It is also possible to omit only the display value to indicate that any display value is acceptable. This affects input and output translate processing differently. When translating on input, any value not already matched is translated to the internal value. When translating on output, the internal value is not translated before it is displayed.

Here is a similar example, but with the branchc variable class changed, to show translate processing when only the display value is omitted:

<!doctype dm system>

<varclass name=branchc type='CHAR 3'>
  <xlatl format=upper>
  </xlatl>
  <xlatl>
    <xlati value=1>RAL
    <xlati value=2>
  </xlatl>

Figure 3. Variable translation

On input, a user-entered value of "CRY" translates to an internal value of "2". On output, an internal value of "2" translates as a displayed value of "2".

It is possible to specify that less than the full input value be entered by the use of the TRUNC attribute. Output translation is not affected.

We'll change the branchc variable class again to illustrate:

     <!doctype dm system>

     <varclass name=branchc type='CHAR 3'>
       <xlatl format=upper>
       </xlatl>
       <xlatl format=none trunc=1>
         <xlati value=1>RAL
         <XLATI VALUE=2>
       </xlatl>

Figure 4. Variable translation

On input, a user-entered value of "R" translates to an internal value of "1". On output, an internal value of "1" translates as a displayed value of "RAL".