Translate Bytes One Byte at a Time (XLATEB1)

Built-in number for XLATEB1 is 414.
XLATEB1 (
         receiver           : address of aggregate(*) for the results of
                              the translation
         source_string      : address of the source bytes to translate
         translate_table    : address of aggregate(256)
         translate_length   : unsigned binary(4) value which specifies the
                              number of bytes to translate
)
 

Description

Translates the data specified by source string into the receiver. Translate length specifies the number of bytes to translate. Each byte of the source string is translated using the corresponding entry in the translation table specified by translate table.

Contrast this operation with XLATEB, which does not support overlapping operands.

Bytes are translated as follows:

• The source byte value is used as an offset and added to the location of translate table.

• The byte value contained in the offset location is the translated byte. This value is copied to the receiver in the same relative position as the original byte value within the source string.

The translation table is exactly 256 bytes in length and specifies the translated values for the 256 possible byte values. The results are undefined if the table is less than 256 bytes.

If receiver overlaps with source string and/or translate table, the overlapped operands are updated for every byte translated. The operation proceeds from left to right, one byte at a time. The following example shows the results of an overlapped operands translate operation. Receiver, source string, and translate table are coincident, with a value of hex 050403020103.

Hex 050403020103 - Initial value

Hex 030403020103 - After the 1st character is translated

Hex 030103020103 - After the 2nd character is translated

Hex 030102020103 - After the 3rd character is translated

Hex 030102020103 - After the 4th character is translated

Hex 030102020103 - After the 5th character is translated

Hex 030102020102 - After the 6th character, the final result

Authorization Required

• None

Lock Enforcement

• None

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment

08 Argument/Parameter

• 0801 Parameter Reference Violation

22 Object Access

• 2202 Object Destroyed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed