Edit (EDIT)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
10E3 Receiver Source Edit mask

Operand 1: Character variable scalar or data-pointer-defined character scalar.

Operand 2: Numeric scalar or data-pointer-defined numeric scalar.

Operand 3: Character variable scalar or data-pointer-defined character scalar.

Bound Program Access 
Built-in number for LBEDIT is 137.
LBEDIT (
        receiver            : address
        receiver_length     : address of unsigned binary(4)
        source              : address of signed binary(4) OR
                              address of unsigned binary(4) OR
                              address of packed decimal (1 to 63 digits) OR
                              address of zoned decimal (1 to 63 digits)
        source_attributes   : address
        mask                : address
        mask_length         : address of unsigned binary(4)
)

The receiver, source and mask parameters correspond to operands 1, 2 and 3 on the EDIT operation.

The source_attributes is a structure which describes the data attributes of the source value. The format of this structure matches that of the third operand on the CVTCN and CVTNC operations.

The receiver_length and mask_length parameters contain the length, in bytes, of the receiver and mask. They are expected to contain a value between 1 and 256.


  -- OR --

EDITPD (
        receiver          : address
        receiver_length   : unsigned binary(4)
        source            : address of packed decimal (1 to 63 digits)
        source_length     : unsigned binary(4)
        mask              : address
        mask_length       : unsigned binary(4)
)

This built-in function supports the EDIT operation when the source contains a packed decimal value. The receiver, source and mask parameters correspond to operands 1, 2 and 3 on the EDIT operation.

The source_length parameter contains the length, in digits, of the source. It is expected to contain a value between 1 and 63.

The receiver_length and mask_length parameters contain the length, in bytes, of the receiver and mask. They are expected to contain a value between 1 and 256.

Description:

The value of a numeric scalar is transformed from its internal form to character form suitable for display at a source/sink device. The following general editing functions can be performed during transforming of the source operand to the receiver operand:

  • Unconditional insertion of a source value digit with a zone as a function of the source value's algebraic sign
  • Unconditional insertion of a mask operand character string
  • Conditional insertion of one of two possible edit mask operand character strings as a function of the source value's algebraic sign
  • Conditional insertion of a source value digit or an edit mask operand replacement character as a function of source value leading zero suppression
  • Conditional insertion of either an edit mask operand character string or a series of replacement characters as a function of source value leading zero suppression
  • Conditional floating insertion of one of two possible edit mask operand character strings as a function of both the algebraic sign of the source value and leading zero suppression
The operation is performed by transforming the source (operand 2) under control of the edit mask (operand 3) and placing the result in the receiver (operand 1).

The edit mask operand (operand 3) is limited to no more than 256 bytes.

Mask Syntax

The source field is converted to packed decimal format. The edit mask contains both control character and data character strings. Both the edit mask and the source fields are processed left to right, and the edited result is placed in the result field from left to right. If the number of digits in the source field is even, the four high-order bits of the source field are ignored and not checked for validity. All other source digits as well as the sign are checked for validity, and a decimal data (hex 0C02) exception is signaled when one is invalid. Overlapping of any of these fields gives unpredictable results.

Nine fixed value control characters can be in the edit mask, hex AA through hex AD and hex AF through hex B3. Four of these control characters specify strings of characters to be inserted into the result field under certain conditions; and the other five indicate that a digit from the source field should be checked and the appropriate action taken.

One variable value control character can be in the edit mask. This control character indicates the end of a string of characters. The value of the end-of-string character can vary with each execution of the instruction and is determined by the value of the first character in the edit mask. If the first character of the edit mask is a value less than hex 40, then that value is used as the end-of-string character. If the first character of the edit mask is a value equal to or greater than hex 40, then hex AE is used as the end-of-string character.

A significance indicator is set to the off state at the start of the execution of this instruction. It remains in this state until a nonzero source digit is encountered in the source field or until one of the four unconditional digits (hex AA through hex AD) or an unconditional string (hex B3) is encountered in the edit mask.

When significance is detected, the selected floating string is overlaid into the result field immediately before (to the left of) the first significant result character.

When the significance indicator is set to the on state, the first significant result character has been reached. The state of the significance indicator determines whether the fill character or a digit from the source field is to be inserted into the result field for conditional digits and characters in conditional strings specified in the edit mask field. The fill character is a hex 40 until it is replaced by the first character following the floating string specification control character (hex B1).

When the significance indicator is in the off state:

  • A conditional digit control character in the edit mask causes the fill character to be moved to the result field.
  • A character in a conditional string in the edit mask causes the fill character to be moved to the result field.
When the significance indicator is in the on state:
  • A conditional digit control character in the edit mask causes a source digit to be moved to the result field.
  • A character in a conditional string in the edit mask is moved to the result field.

The following control characters are found in the edit mask field.

End-of-String Character

One of these control characters (a value less than hex 40 or hex AE) indicates the end of a character string and must be present even if the string is null.

Static Field Character

Hex AF
This control character indicates the start of a static field. A static field is used to indicate that one of two mask character strings immediately following this character is to be inserted into the result field, depending upon the algebraic sign of the source field. If the sign is positive, the first string is to be inserted into the result field; if the sign is negative, the second string is to be inserted.

Static field format:

<Hex AF> <positive string>. . .<less than hex 40> <negative string>. . .<hex AE>

OR

<Hex AF> <positive string>. . .<hex AE> <negative string>. . .<hex AE>

Floating String Specification Field Character

Hex B1
This control character indicates the start of a floating string specification field. The first character of the field is used as the fill character; following the fill character are two strings delimited by the end-of-string control character. If the algebraic sign of the source field is positive, the first string is to be overlaid into the result field; if the sign is negative, the second string is to be overlaid.

The string selected to be overlaid into the result field, called a floating string, appears immediately to the left of the first significant result character. If significance is never set, neither string is placed in the result field.

Conditional source digit positions (hex B2 control characters) must be provided in the edit mask immediately following the hex B1 field to accommodate the longer of the two floating strings; otherwise, a length conformance (hex 0C08) exception is signaled. For each of these B2 strings, the fill character is inserted into the result field, and source digits are not consumed. This ensures that the floating string never overlays bytes preceding the receiver operand.

Floating string specification field format:

<Hex B1> <fill character> <positive string>. . . <end-of-string character> <negative string>. . .<end-of-string character>

followed by

<Hex B2>. . .

Conditional String Character

Hex B0
This control character indicates the start of a conditional string, which consists of any characters delimited by the end-of-string control character. Depending on the state of the significance indicator, this string or fill characters replacing it is inserted into the result field. If the significance indicator is off, a fill character for every character in the conditional string is placed in the result field. If the indicator is on, the characters in the conditional string are placed in the result field.

Conditional string format:

<Hex B0> <conditional string>. . .<end-of-string character>

Unconditional String Character

Hex B3
This control character turns on the significance indicator and indicates the start of an unconditional string that consists of any characters delimited by the end-of-string control character. This string is unconditionally inserted into the result field regardless of the state of the significance indicator. If the indicator is off when a B3 control character is encountered, the appropriate floating string is overlaid into the result field before (to the left of) the B3 unconditional string (or to the left of where the unconditional string would have been if it were not null).

Unconditional string format:

<Hex B3> <unconditional string>. . .<end-of-string character>

Control Characters That Correspond to Digits in the Source Field

Hex B2
This control character specifies that either the corresponding source field digit or the floating string (hex B1) fill character is inserted into the result field, depending on the state of the significance indicator. If the significance indicator is off, the fill character is placed in the result field; if the indicator is on, the source digit is placed. When a source digit is moved to the result field, the zone supplied is hex F. When significance (that is, a nonzero source digit) is detected, the floating string is overlaid to the left of the first significant character.
Control characters hex AA, hex AB, hex AC, and hex AD turn on the significance indicator. If the indicator is off when one of these control characters is encountered, the appropriate floating string is overlaid into the result field before (to the left of) the result digit.
Hex AA
This control character specifies that the corresponding source field digit is unconditionally placed in the 4 low-order bits of the result field with the zone set to a hex F.
Hex AB
This control character specifies that the corresponding source field digit is unconditionally placed in the result field. If the sign of the source field is positive, the zoned portion of the digit is set to hex F (the preferred positive sign); if the sign is negative, the zone portion is set to hex D (the preferred negative sign).
Hex AC
This control character specifies that the corresponding source field digit is unconditionally placed in the result field. If the algebraic sign of the source field is positive, the zone portion of the result is set to hex F (the preferred positive sign); otherwise, the source sign field is moved to the result zone field.
Hex AD
This control character specifies that the corresponding source field digit is unconditionally placed in the result field. If the algebraic sign of the source field is negative, the zone is set to hex D (the preferred negative sign); otherwise, the source field sign is moved to the zone position of the result byte.

The following table provides an overview of the results obtained with the valid edit conditions and sequences.

Table 1. Valid Edit Conditions and Results
 
Mask
Character
 
Previous
Significance
Indicator
 
 
Source
Digit
 
 
Source
Sign
 
 
Result
Character(s)
 
Resulting
Significance
Indicator
 
AF Off/On Any Positive Positive string inserted No Change
Off/On Any Negative Negative string inserted No Change
AA Off 0–9 Positive Positive floating string overlaid; hex F, source digit On
Off 0–9 Negative Negative floating string overlaid; hex F, source digit On
On 0–9 Any Hex F, source digit On
AB Off 0–9 Positive Positive floating string overlaid; hex F, source digit On
Off 0–9 Negative Negative floating string overlaid; hex D, source digit On
On 0–9 Positive Hex F, source digit On
On 0–9 Negative Hex D, source digit On
AC Off 0–9 Positive Positive floating string overlaid; hex F, source digit
Off 0–9 Negative Negative floating string overlaid; source sign and digit On
On 0–9 Positive Hex F, source digit On
On 0–9 Negative Source sign and digit On
AD Off 0–9 Positive Positive floating string overlaid; source sign and digit On
Off 0–9 Negative Negative floating string overlaid; hex D, source digit On
On 0–9 Positive Source sign and digit On
On 0–9 Negative Hex D, source digit On
B0 Off Any Any Insert fill character for each B0 string character Off
On Any Any Insert B0 character string On
B1 (including necessary B2s) Off Any Any Insert the fill character for each B2 character that corresponds to a character in the longer of the two floating strings No Change
B2 (not for a B1 field) Off 0 Any Insert fill character Off
Off 1–9 Positive Overlay positive floating string and insert hex F, source digit On
Off 1–9 Negative Overlay negative floating string and insert hex F, source digit On
On 0–9 Any Hex F, source digit
B3 Off Any Positive Overlay positive floating string and insert B3 character string On
Off Any Negative Overlay negative floating string and insert B3 character string On
On Any Any Insert B3 character string On
Note:
  1. Any character is a valid fill character, including the end-of-string character.
  2. Hex AF, hex B1, hex B0, and hex B3 strings must be terminated by the end-of-string character even if they are null strings.
  3. If a hex B1 field has not been encountered (specified) when the significance indicator is turned on, the floating string is considered to be a null string and is therefore not used to overlay into the result field.
  4. If the positive and negative strings of a static field are of unequal length, additional static fields are necessary to ensure that the sum of the lengths of the positive strings equal the sum of the lengths of the negative strings; otherwise, a length conformance (hex 0C08) exception is signaled because the receiver length does not correspond to the length implied by the edit mask and source field sign.

The following figure indicates the valid ordering of control characters in an edit mask field.

Figure 1. Edit Mask Field Control Characters
Edit Mask Field Control Characters

Explanation:

Condition
Definition
0
Both X and Y can appear in the edit mask field in either order.
1
Y cannot precede X.
2
X cannot precede Y.
3
Both control characters (two B1's) cannot appear in an edit mask field.

Violation of any of the above rules will result in an edit mask syntax (hex 0C05) exception.

The following steps are performed when the editing is done:

  • Convert Source Value to Packed Decimal
    • The numeric value in the source operand is converted to a packed decimal intermediate value before the editing is done. If the source operand is binary, the attributes of the intermediate packed field before the edit are calculated as follows:
      • Binary(2) = packed (5,0) or
      • Binary(4) = packed (10,0)

      A data-pointer-defined source operand with 8 byte binary attributes is not supported and will cause a scalar value invalid (hex 3203) exception to be signaled.

  • Edit
    • The editing of the source digits and mask insertion characters into the receiver operand is done from left to right.
  • Insert Floating String into Receiver Field
    • If a floating string is to be inserted into the receiver field, this is done after the other editing.

Edit Digit Count Exception

An edit digit count (hex 0C04) exception is signaled when:

  • The end of the source field is reached and there are more control characters that correspond to digits in the edit mask field.
  • The end of the edit mask field is reached and there are more digit positions in the source field.
Edit Mask Syntax Exception

An edit mask syntax (hex 0C05) exception is signaled when an invalid edit mask control character is encountered or when a sequence rule is violated.

Length Conformance Exception

A length conformance (hex 0C08) exception is signaled when:

  • The end of the edit mask field is reached and there are more character positions in the result field.
  • The end of the result field is reached and more positions remain in the edit mask field.
  • The number of B2s following a B1 field cannot accommodate the longer of the two floating strings.

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
    • 0C02 Decimal Data
    • 0C04 Edit Digit Count
    • 0C05 Edit Mask Syntax
    • 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
  • 32 Scalar Specification
    • 3201 Scalar Type Invalid
    • 3202 Scalar Attributes 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