Translate with Table and DBCS Skip (XLATWTDS)

Operand 2: Binary(4) scalar.

Operand 3: Character scalar.

Built-in number for XLATWTDS is 148.
XLATWTDS (
          target   : address
          length   : address of unsigned binary(4)
          table    : address
)

Description

The simple (single byte) characters in the target are translated under control of the translate table, for the length defined by operand 2. The extended (double byte) character portions of the target are bypassed and not translated. The operation begins with the leftmost character of operand 1 and proceeds character-by-character, left-to-right, skipping over any Double byte character (DBCS) data portions.

The target, operand 1, should have double byte character data surrounded by a shift out control character (SO = hex 0E) and a shift in control character (SI= hex 0F). Once a SO character is encountered, the translating of single byte characters halts. The operation will then proceed double byte character-by-double byte character until a SI character is encountered. This shift in character is then used to restart the translating of single byte characters.

The length operand, operand 2, is the number of bytes and must contain a value between 1 and 32,767. For length values outside this range a scalar value invalid  (hex 3203) exception is signaled.

Single byte characters are translated as follows:

• The target character is used as an offset and added to the location of operand 3.

• The character contained at the offset location of operand 3 is the translated character. This character replaces the original character in the target.

The following example shows the step-by-step results of this translate operation. The translate table for this example has the following hex value: C3D406C5D504C1C2C4C5C6C7C8C9C1C6

Hex 05040ED2D2E1E10F03 - Initial target value

Hex 04040ED2D2E1E10F03 - After the 1st character is translated

Hex 04D50ED2D2E1E10F03 - After the 2nd character is translated

Hex 04D50ED2D2E1E10F03 - SO character encountered, skip the DBCS portion

Hex 04D50ED2D2E1E10F03 - Resume translating after SI control character

Hex 04D50ED2D2E1E10FC5 - Translate 9th character

Hex 04D50ED2D2E1E10FC5 - Final target value

The translate table, operand 3, is assumed to be 256 bytes long. If the table is less than 256 characters long, and a target character specifies an offset beyond the end of the table, the resultant characters are obtained from byte locations in the space following translate table. If that portion of the space is not currently allocated, a space addressing violation  (hex 0601) exception is signaled.

This operation only translates the target string and does not validate the double byte portions of the target. For example, if a DBCS portion of the target string is preceded by the Shift Out control character, but missing the closing Shift In character, then an invalid extended character data  (hex 0C12) exception will NOT be signaled. However, the Copy Extended Characters Left-Adjusted With Pad (CPYECLAP) instruction can be used to validate extended character data, if necessary.

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

10 Damage Encountered

• 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

• 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

32 Scalar Specification

• 3201 Scalar Type Invalid
• 3203 Scalar Value Invalid

36 Space Management

• 3601 Space Extension/Truncation

44 Protection Violation

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