Copy Bytes with Pointers (CPYBWP)

Instruction Syntax

Operand 1: Character variable scalar, space pointer machine object, or pointer data object.

Operand 2: Character variable scalar, space pointer machine object, pointer data object or null.

Built-in number for CPYBWP is 14.
CPYBWP (
        receiver   : address
        source     : address
        length     : unsigned binary(4)
)
 
The receiver and source operands correspond to operands 1 and 2 on the CPYBWP operation. 
The length operand contains the length, in bytes, of the receiver and source operands. It is expected to contain a value between 1 and 16,776,704. 

Description:

This instruction copies either the pointer value or the byte string specified for the source operand into the receiver operand depending upon whether or not a space pointer machine object is specified as one of the operands.

If either operand is a character variable scalar, it can have a length as great as 16,776,191 bytes.

Operations involving space pointer machine objects perform a pointer value copy operation for only space pointer values or the pointer does not exist state. Due to this, a space pointer machine object may only be specified as an operand in conjunction with another pointer or a null second operand. The pointer does not exist state is copied from the source to the receiver pointer without signaling the pointer does not exist (hex 2401) exception. Source pointer data objects must either be not set or contain a space pointer value when being copied into a receiver space pointer machine object. Receiver pointer data objects will be set with either the system default pointer does not exist value or the space pointer value from a source space pointer machine object.

If the source operand is a synchronization pointer, the pointer will be copied to the receiver. However, the copied pointer is not useful, because a synchronization pointer is defined to reside at only a single location in memory. Attempting to use a copied synchronization pointer will cause unpredictable results.

Normal pointer alignment checking is performed on a pointer data object specified as an operand in conjunction with a space pointer machine object.

Operations not involving space pointer machine objects, those involving just data objects as operands, perform a byte string copy of the data for the specified operands.

The value of the byte string specified by operand 2 is copied to the byte string specified by operand 1 (no padding done).

The byte string identified by operand 2 can contain the storage forms of both scalars and pointers. Normal pointer alignment checking is not done.

Alignment requirements for this instruction vary, depending on the length of the data being copied, whether bound or non-bound program access is used, and if non-bound program access is used, whether the CPYBWP override is in effect from the Override Program Attributes (OVRPGATR) instruction. Alignment is not checked when the specified copy length is less than 16 bytes, because then no pointer could be copied. (Recall that space pointer machine objects have no specified length, so length stipulations do not apply to their use.) For bound program access, and for non-bound program access when OVRPGATR has not been used to override CPYBWP,

When the OVRPGATR instruction is used to override this instruction, the alignment requirement is removed. If the space addressability alignment of the two operands is the same relative to 16-byte multiple boundary, then this instruction will work the same as stated above. If the space addressability alignment is different, then this instruction will work like a Copy Bytes Left Adjusted (CPYBLA) and the pointer attributes of any complete pointers in the source are not preserved in the receiver.

If a pointer data object operand contains a data pointer value upon execution of the instruction, the pointer storage form is copied rather than the scalar described by the data pointer value. The character variable scalar reference allowed on either operand cannot be described through a data pointer value.

The length of the operation is equal to the length of the shorter of the two operands. The copying begins with the two operands left-adjusted and proceeds until completion of the shorter operand.

Operand 1 can specify a space pointer machine object only when operand 2 is a space pointer or null.

If operand 2 is null, operand 1 must define a pointer reference. When operand 2 is null, the pointer identified by operand 1 is set to the system default pointer does not exist value.

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
  • 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