Translate (XLATE)

Instruction Syntax

Operand 1: Character variable scalar.

Operand 2: Character scalar.

Operand 3: Character scalar or null.

Operand 4: Character scalar.

Description:

Selected characters in the string value of the source operand are translated into a different encoding and placed in the receiver operand. The characters selected for translation and the character values they are translated to are indicated by entries in the position and replacement strings. All the operands must be character strings. The source and receiver values must be of the same length. The position and replacement operands can differ in length. If operand 3 is null, a 256-character string is used, ranging in value from hex 00 to hex FF (EBCDIC collating sequence).

The operation begins with all the operands left-adjusted and proceeds character by character, from left to right until the character string value of the receiver operand is completed.

Each character of the source operand value is compared with the individual characters in the position operand. If a character of equal value does not exist in the position string, the source character is placed unchanged in the receiver operand. If a character of equal value is found in the position string, the corresponding character in the same relative location within the replacement string is placed in the receiver operand as the source character translated value. If the replacement string is shorter than the position string and a match of a source to position string character occurs for which there is no corresponding replacement character, the source character is placed unchanged in the receiver operand. If the replacement string is longer than the position string, the rightmost excess characters of the replacement string are not used in the translation operation because they have no corresponding position string characters. If a character in the position string is duplicated, the first occurrence (leftmost) is used.

If operands overlap but do not share all of the same bytes, results of operations performed on these operands are not predictable. If overlapped operands share all of the same bytes, the results are predictable when direct addressing is used. If indirect addressing is used (that is, based operands, parameters, strings with variable lengths, and arrays with variable subscripts), the results are not always predictable.

The receiver, source, position, and replacement operands can be variable length substring compound operands.

Substring operand references that allow for a null substring reference (a length value of zero) may be specified for all of the operands on this instruction. The effect of specifying a null substring reference for either the position or replacement operands is that the source operand is copied to the receiver with no change in value. The effect of specifying a null substring reference for both the receiver and the source operands (they must have the same length) is that no result is set.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 0C Computation
  • 0C08 Length Conformance
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1044 Partial System Object Damage
• 1C Machine-Dependent
  • 1C03 Machine Storage Limit Exceeded
• 20 Machine Support
  • 2002 Machine Check
  • 2003 Function Check
• 22 Object Access
  • 2201 Object Not Found
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2208 Object Compressed
  • 220B Object Not Available
• 24 Pointer Specification
  • 2401 Pointer Does Not Exist
  • 2402 Pointer Type Invalid
• 2E Resource Control Limit
  • 2E01 User Profile Storage Limit Exceeded
• 36 Space Management
  • 3601 Space Extension/Truncation
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed