Copy Extended Characters Left-Adjusted With Pad (CPYECLAP)

Operand 2: Data-pointer-defined character scalar.

Operand 3: Character(3) scalar or null.

Built-in number for CPYECLAP is 412.
CPYECLAP (
          receiver_pointer   : address of data pointer
          source_pointer     : address of data pointer
          pad                : address OR
                               null operand
)

Description

The extended character string value of the source operand is copied to the receiver operand.

The operation is performed at the length of the receiver operand. If the source operand is shorter than the receiver, the source operand is copied to the leftmost bytes of the receiver and the excess bytes of the receiver are assigned the appropriate value from the pad operand.

The pad operand, operand 3, is three bytes in length and has the following format:

If the pad operand is more than three bytes in length, only its leftmost three bytes are used. Specifying a null pad operand results in default pad values of hex 40, for single byte, and hex 4040, for double byte, being used. The single byte pad value and the first byte of the double byte pad value cannot be either a shift out control character (SO = hex 0E) value or a shift in control character (SI = hex 0F) value. Specification of such an invalid value results in the signaling of the scalar value invalid  (hex 3203) exception.

Operands 1 and 2 must be specified as data pointers which define either a simple (single byte) character data field or one of the extended (double byte) character data fields.

Support for usage of a data pointer defining an extended character scalar value is limited to this instruction. Usage of such a data pointer defined value on any other instruction is not supported and results in the signaling of the scalar type invalid  (hex 3201) exception.

For more information on support for extended character data fields, refer to the Set Data Pointer Attributes (SETDPAT) and Materialize Pointer (MATPTR) instructions.

Four data types are supported for data pointer definition of extended (double byte) character fields, OPEN, EITHER, ONLYNS and ONLYS. Except for ONLYNS, the double byte character data must be surrounded by a shift out control character (SO = hex 0E) and a shift in control character (SI = hex 0F).

• The ONLYNS field only contains double byte data with no SO, SI delimiters surrounding it.

• The ONLYS field can only contain double byte character data within a SO..SI pair.

• The EITHER field can consist of double byte character or single byte character data but only one type at a time. If double byte character data is present it must be surrounded by an SO..SI pair.

• The OPEN field can consist of a mixture of double byte character and single byte character data. If double byte character data is present it must be surrounded by an SO..SI pair.

Specifying an extended character value which violates the above restrictions results in the signaling of the invalid extended character data  (hex 0C12) exception.

The valid copy operations which can be specified on this instruction are the following:

Table 1. Valid copy operations for CPYECLAP

Specifying a copy operation other than the valid operations defined above results in the signaling of the invalid extended character operation  (hex 0C13) exception.

When the copy operation is for a source of type ONLYNS (no SO/SI delimiters) being copied to a receiver which is not ONLYNS, SO and SI delimiters are implicitly added around the source value as part of the copy operation.

When the source value is longer than can be contained in the receiver, truncation is necessary and the following truncation rules apply:

1. Truncation is on the right (like simple character copy operations).

2. When the string to be truncated is a single byte character string, or an extended character string when the receiver is ONLYNS, bytes beyond those that fit into the receiver are truncated with no further processing needed.

3. When the string to be truncated is an extended character string and the receiver is not ONLYNS, the bytes that fall at the end of the receiver are truncated as follows:

   1. When the last byte that would fit in the receiver is the first byte of an extended character, that byte is truncated and replaced with an SI character.

   2. When the last byte that would fit in the receiver is the second byte of an extended character, both bytes of that extended character are truncated and replaced with a SI character followed by a single byte pad value. This type of truncation can only occur when converting to an OPEN field.

When the source value is shorter than that which can be contained in the receiver, padding is necessary. One of three types of padding is performed:

1. Double byte (DB) - the source value is padded on the right with double byte pad values out to the length of the receiver.

2. Double byte concatenated with a SI value (DB||SI) - the source double byte value is padded on the right with double byte pad values out to the second to last byte of the receiver and an SI delimiter is placed in the last byte of the receiver.

3. Single byte (SB) - the source value is padded on the right with single byte pad values out to the length of the receiver.

The type of padding performed is determined by the type of operands involved in the operation:

1. If the receiver is ONLYNS, DB padding is performed.

2. If the receiver is ONLYS, DB||SI padding will be performed.

3. If the receiver is EITHER and the source contained a double byte value, DB||SI padding is performed.

4. If the receiver is EITHER and the source contained a single byte value, SB padding is performed.

5. If the receiver is OPEN, SB padding is performed.

The above padding rules cover all the operand combinations which are allowed on the instruction. A complete understanding of the operand combinations allowed (prior diagram), and the values which can be contained in the different operand types is necessary to appreciate that these rules do cover all the valid combinations.

Authorization Required

• None

Lock Enforcement

• None

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range
• 0604 External Data Object Not Found

08 Argument/Parameter

• 0801 Parameter Reference Violation

0C Computation

• 0C12 Invalid Extended Character Data
• 0C13 Invalid Extended Character Operation

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

32 Scalar Specification

• 3201 Scalar Type 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