XLATL (Translate List)

The XLATL tag defines a translate list for a variable class.

Syntax


>>-<XLATL--+--------------------------------------+------------->
           |         .-NONE---------------------. |   
           '-FORMAT=-+-UPPER--------------------+-'   
                     '-NONE--TRUNC--=--+-n----+-'     
                                       '-char-'       

>--+------------------------+-->--</XLATL>---------------------><
   '-MSG=message-identifier-'

Parameters

FORMAT=NONE | UPPER: This attribute defines the type of translation. NONE specifies that enclosed XLATI tags are to be used to translate the value on an item for item basis. UPPER specifies that the variable value is translated to uppercase.
TRUNC=n | char: This attribute defines the type of truncation to be performed on input values. It is valid only when FORMAT=NONE. If a number is provided, truncation occurs at the length indicated. If a nonnumeric character is provided, truncation occurs at the first occurrence of that character.
MSG=message-identifier: This attribute specifies the ID of a message to be issued for the error condition that results when an input translation fails because the user entered a value not specified in the list. Specifying an XLATI tag with no internal-value and no displayed-value ensures that any value not in the list is accepted without error. If no message ID is specified and an error occurs, the message-identifier specified on the VARCLASS tag is used. If no message-identifier is specified on the XLATL tag or the VARCLASS tag, no message is displayed.
Note: This message is not used if translation on output fails. The variable value is displayed as is, subject to whatever size restrictions apply to the field.

Comments

The XLATL tag defines a translate list for a variable class. XLATI tags, which define the elements of the translation list, are coded within the XLATL tag. A translation list is defined within a VARCLASS tag.

If FORMAT=NONE is specified, it is expected that there are XLATI tags within the XLATL definition. If FORMAT=UPPER is specified, no XLATI tags are accepted in the XLATL definition.

Translation lists are optional and provide a means of translating between a displayed value and the internal value of the variable. Translation can occur on input (the translation result is stored in the variable pool), on output (the value from the pool is translated before the user sees it), or both, depending on the USAGE attribute of the DTAFLD tag that is associated with the variable. Translation for table display is not supported by ISPF. See the z/OS ISPF Dialog Developer's Guide and Reference for additional information about the TRANS function.

Restrictions

The XLATL tag requires an end tag.
You must code the XLATL tag within a VARCLASS definition. See VARCLASS (Variable Class) for a complete description of this tag.
You must code all XLATL tags before any CHECKL tags in the same variable class.

Processing

Table 1. Tags you can code within an XLATL definition
Tag	Reference	Usage	Required
XLATI	XLATI (Translate Item)	Multiple	Yes

Examples

Here is source file markup that includes translation of user input for monthcls to uppercase followed by a translation list of the abbreviated month to an internal value. If no match is found, message abcd003 is issued. The example also shows the use of uppercase translation before a check for a list of values for Type of heating.

<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=monthcls type='char 3'>
   <XLATL FORMAT=upper>
   </XLATL>
   <XLATL MSG=abcd003>
       <XLATI VALUE=11>NOV
       <XLATI VALUE=12>DEC
       <XLATI VALUE=01>JAN
       <XLATI VALUE=01>FEB
       <XLATI VALUE=03>MAR
   </XLATL>

<VARCLASS NAME=costcls TYPE='numeric 6' MSG=abcd001>

<VARCLASS NAME=typecls TYPE='char 4'>
   <XLATL FORMAT=upper>
   </XLATL>
   <CHECKL MSG=abcd002>
      <CHECKI TYPE=values Parm1=EQ Parm2= 'GAS OIL ELEC'>
   </CHECKL>

<VARLIST>
   <VARDCL NAME=month VARCLASS=monthcls>
   <VARDCL NAME=cost VARCLASS=costcls>
   <VARDCL NAME=heat VARCLASS=typecls>
</VARLIST>

<PANEL NAME=xlatl KEYLIST=keylxmp>Heating Cost Survey
   <TOPINST>Complete the information below and then press Enter.
   <AREA>
     <DTACOL PMTWIDTH=20 DESWIDTH=30>
        <DTAFLD DATAVAR=month ENTWIDTH=3>Winter month
          <DTAFLDD>Enter Nov, Dec, Jan, Feb, or Mar
        <DTAFLD DATAVAR=cost ENTWIDTH=6>Heating cost
        <DTAFLD DATAVAR=heat ENTWIDTH=4>Type of heating
          <DTAFLDD>Enter Oil, Gas, or Elec
     </DTACOL>
   </AREA>
   <BOTINST>Thank you for your participation.
</PANEL>

<MSGMBR NAME=abcd00>
  <MSG SUFFIX=1>Heating cost must be numeric
  <MSG SUFFIX=2>Type of heating must be "Gas", "Oil", or "Elec"
  <MSG SUFFIX=3>Winter month must be "Nov","Dec", "Jan", "Feb", or "Mar"
</MSGMBR>