Verbs and Built-in Functions › &TRANS

&TRANS

Performs character translation within a string.

&TRANS { C'x1 y1....  xn yn | X'xx1 yy1.... xxn yyn |
         UPPER | LOWER | PRINT |
         NLUPPER [ =lc ] | NLLOWER [ =lc ] }
       string

&TRANS is a built-in function that translates occurrences of nominated characters, which is specified either in character form or as a hexadecimal value, to an alternative character or hexadecimal value. The translation occurs when the source string is assigned to the target variable, which is specified to the left of the &TRANS function. The source string is unchanged. Translation occurs after substitution of any variables in the source string. The source string is therefore assumed to start one blank position following the end of the translation control argument. Any additional blanks will be treated as part of the source string and will be translated if applicable, as shown in the second example.

Operands:

C'x¹ y¹ … xⁿ yⁿ

Indicates that all occurrences of the character x^m in the source string are to be replaced by the character y^m that is paired with x^m in the translate control string.

X'xx¹ yy¹ … xxⁿ yyⁿ

Indicates that all occurrences of the character whose hexadecimal value is xx^m in the source string are to be replaced by the character whose hexadecimal value is yy^m that is paired with xx^m in the translate control string.

UPPER

Translates any lowercase characters to uppercase.

LOWER

Translates any uppercase characters to lowercase.

PRINT

Translates non-printable characters to blanks.

NLUPPER [ =lc ]

Uses the language code of the user to decide the character set that is used for the translation. A predefined language code can optionally be specified, for example, NLUPPER=GR.

When the language code (either that of the user or the supplied value) does not match one of the supported language codes, the language code of the system is used to perform the translation. When the language code of the system is not one of the supported values, the value UK is used.

NLLOWER [ =lc ]

Uses the language code of the user to decide the character set that is used for the translation. A predefined language code can optionally be specified, for example, NLLOWER=GR.

When the language code (either that of the user or the supplied value) does not match one of the supported values, the language code of the system is used to perform the translation. When the language code of the system is not one of the supported values, the value UK is used.

string

Data which is to be translated.

Examples: &TRANS

&A = ABC
&A1 = ABD
&B = &TRANS C'A1B2C3' &A &A1    -* (single blank after
                                -* translate argument)
                                -* Result &B = 123 12D

&A = ABC
&A1 = ABD
&B = &TRANS C'A1B2C3 %'  &A &A1 -* (two blanks after translate
                                -* argument
                                -* Result &B = %123%12D

&A = ABC
&B = &TRANS X'C1C2C3C4' &A      -* Result &B = BBD

&A = john smith
&B = &TRANS UPPER &A            -* Result &B = JOHN SMITH

Notes:

Two adjacent single quotes must be used if a quote forms part of the translate control string.

This function is particularly useful for screening data that is to be displayed on a panel using the preparse facility.