1 of 23

IBM^® z/Architecture�EDIT (ED) and EDIT AND MARK (EDMK) Instructions

Dan Greiner – IBM Architect Emeritus

1

This presentation will discuss two of the instructions that contribute to the complex-instruction-set-computer (CISC) nature of IBM’s z/Architecture systems:

EDIT (ED)
EDIT AND MARK (EDMK)

These instructions are certainly not new to the architecture; they have been around since the original IBM System/360 was introduced in 1964.

The original ED and EDMK instructions in the S/360 had the ability to produce zoned-decimal results in either of the following two formats, depending on a bit in the program-status word (PSW):

Extended binary-coded decimal interchange code (EBCDIC)
American standard code for information interchange (ASCII)

No IBM operating system ever supported this dual-format feature, and it was dropped with the advent of the S/370; the results have been in EBCDIC ever since.

In the April 1987 issue of the Communications of the ACM, two of the original S/360 instruction-set architects – Richard Case and Andris Padegs (Gene Amdahl was the third ISA architect) – were asked if there was any instructions that were not really necessary in the design of the S/360. Their answer was unequivocal: EDIT and EDIT AND MARK! However, by the time of this interview in 1987, these instructions were so ubiquitous that it was unthinkable to ever consider removing them.

2 of 23

The Legal Stuff

Trademarks:

IBM is a registered trademark of the International Business Machines Corporation in the United States, other countries, or both. The following terms which may appear in this presentation are trademarks or registered trademarks of the International Business Machines Corporation in the United States, other countries, or both:

ESA/390
z/Architecture
z/OS
z/VM

Linux is a registered trademark of Linus Torvalds in the United States, other countries or both.
Unicode is a registered trademark of Unicode, Incorporated in the United States, other countries, or both.
Other trademarks and registered trademarks are the properties of their respective companies.

All information contained in this document is subject to change without notice. All information contained in this document was obtained in laboratory environment and is presented as an illustration. The results obtained in other operating environments may vary.
While the information contained herein is believed to be accurate, such information is preliminary, and should not be relied upon for accuracy or completeness, and no representations or warranties of accuracy or completeness are made.
The information in contained in this document is provided on an “AS IS” basis. In no event will the author be liable for damages arising directly or indirectly from any use of the information contained in this document.

2

Giving credit where credit is due, the trademarks cited on this page are registered by the corporations or organizations cited.

The material in this presentation is derived from the IBM z/Architecture Principles of Operation (SA22-7832-12) which completely describes the architecture of the EDIT and EDIT AND MARK instructions (and is fully protected by copyright by the IBM Corporation). However, as any reader of the PoO well knows, it does not always describe the architecture following the path of least astonishment.

This presentation attempts to illustrate in a visual manner how these two instructions operate. You might think of it as the graphic novel version of the ED and EDMK instructions.

To whatever extent this presentation builds upon the concepts of the PoO, the author claims copyright to that new material.

3 of 23

ED & EDMK Uses

How to take this signed packed-decimal value …

31

41

59

26

53

58

97

9C

3

.

1

4

1

,

5

9

2

,

6

5

3

,

5

8

9

,

7

9

… and turn it into this printable EBCDIC value (in 1 instruction).

00

12

34

56

7C

$

1

2

,

3

4

5

.

6

7

00

03

99

5A

*

3

9

.

9

5

*

How to take this signed packed-decimal value …

… and turn it into this printable EBCDIC value (in 1 instruction).

How to take this signed packed-decimal value …

… and turn it into this printable EBCDIC value (in 2 instructions).

3

The primary use of ED and EDMK instructions is to translate packed-decimal data – signed or unsigned – into the zoned-decimal format suitable for displaying or printing. Features of the instructions include:

The ability to format one or more packed-decimal fields into zoned-decimal fields.
The ability to replace insignificant leading zeros with a fill byte. A fill byte may be as common as a blank, or for applications such as check writing, a security character such as an asterisk.
The ability to separate resulting digits with delineating characters such as commas, periods, or other characters. For example, “1,234,567.89”, where the commas and period are added.
For EDIT AND MARK (EDMK), the ability to indicate the address of the leading significant digit of the rightmost edited field. This can be useful for inserting a currency symbol (e.g., $, £, ¥, €) or a sign indication to the left of the formatted number.

In the first example on this slide, the input value is a signed packed-decimal value of the first 15 digits of pi. The ED or EDMK instruction can format it such that the result includes the decimal point, and commas separating each order of magnitude of the fraction. This conversion is accomplished by the single ED or EDMK instruction.

In the second example, a packed-decimal value is converted into a value with leading asterisks replacing insignificant leading zeros. This is useful in applications such as check printing, where a security character replaces the leading zeros. Again, this is accomplished in either a single ED or EDMK.

The third example is applicable to EDMK only. In this example, a packed-decimal currency value that can accommodate up to 9 trillion dollars ($10⁹and change) is converted, and the leading zeros are replaced with blanks. The EDMK instruction returns the address of the leftmost significant digit (the “1”) in general register 1. The currency symbol (“$”) is added by using the MVIY instruction to target the location one byte to the left of that designated by GR1 (e.g., MVIY -1(1),C’$’).

Note, these examples illustrate the editing of a single field. As we will see later, multiple fields may be edited by a single instruction.

4 of 23

EDIT (ED)

ED D₁,(L,B₁),D₂,(B₂) [SS-a]

DE

L

B₂

D₂

B₁

D₁

The first operand designates the location of the pattern bytes which are:

Replaced with a 2^nd-op source digit
Replaced with a fill byte, or
Unchanged

The second operand designates the location of the source bytes consisting of signed or unsigned packed-decimal data

n

s

//

Pat

//

The L (length) field designates one less than the number of bytes in the first operand.

4

The EDIT instruction (mnemonic ED) is a 6-byte storage-and-storage- (SS-) format instruction that is present in all z/Architecture-capable processors (and in their predecessors all the way back to the original S/360). All SS-format instructions have a single-byte operation code in bits 0-7; in this case, hexadecimal DE. (Note: More than one person has confused the instruction’s mnemonic ED with the hexadecimal opcode DE; so, it’s not just my latent dyslexia at work.)

The first operand consists of a classic base-register-and-displacement designation of a location in memory containing pattern bytes. The processing of individual pattern bytes is dependent on their content, as follows:

It may be replaced with the zoned-decimal equivalent of the next available packed-decimal source digit from the second operand.
It may be replaced with a fill byte (which is always the first byte of the leftmost pattern byte).
It may remain unchanged.

Details on the pattern bytes are provided in a few slides.

The length of the first operand in bytes is designated by the L field in bits 8-15 of the instruction. Like many instructions in which the length is encoded within, the length in the instruction text is one less than the true length (as coded in the assembler statement). Thus, an L value of zero in the instruction text means the first operand is one byte in length; a value of FF hex in the instruction text means the first operand is 256 bytes in length.

The second operand consists of a classic base-register-and-displacement designation of a location in memory containing the source bytes. The source bytes are in either the signed or unsigned packed-decimal format. The length of the second operand is dependent on the pattern bytes in the first operand.

Reminder: In the packed-decimal format, each byte comprises two four-bit digits. Excepting for the rightmost byte of a signed packed-decimal field, each of the four-bit digits must be between 0 and 9. If a value of hex A-F is found in any left digit, a general-operand data exception is recognized, and the instruction is either suppressed or terminated. The rightmost digit of a signed packed-decimal field is the sign code: Hex B and D indicate negative, and hex A, C, E, and F indicate positive.

5 of 23

Significance Indicator

The significance indicator (SI) is an internal flag that has multiple functions:

SI controls the handling of the fill byte:

When a leading packed-decimal zero from the 2^nd operand is converted to a zoned zero value in the 1^st operand.
When handling a message byte (more later)

SI controls the setting of the condition code based on the rightmost (or only) field being edited in the 1^st operand.

SI is set as follows:

Off (0):

When instruction execution begins
When a field separator is encountered in the 1^st operand
When a 2^nd-operand source byte contains a plus code in bits 4-7.

On (1):

When a significance-starter pattern byte encountered in the 1^st operand.
When nonzero packed-decimal source digit is selected in the 2^nd operand (and the sign code of the source byte is not plus).

5

In the following slides, we will mention an internal control that is crucial to the operation of the ED and EDMK instructions: the significance indicator. SI is a binary value that is either “off” (0) or “on” (1). The term significance indicator is somewhat incomplete, as the SI actually serves two purposes:

Processing of the fill byte depending on the significance of the digit being processed.
Indicating the condition code.

SI is set to the off (0) state:

At the beginning of the ED and EDMK’s execution.
After a first-operand pattern byte called a field separator (FS) is encountered (more on FS in a few slides).
After a source byte is examined that has a packed-decimal plus code in the rightmost four bits (that is, a value of hex A, C, E, or F).

SI is set to the “on” (1) state:

When a significance starter (SS) pattern byte is encountered, and the second-operand source digit selected is a valid decimal digit whose source byte does not contain a plus code.
When a digit selector (DS) pattern byte is encountered, and the second-operand source digit selected a valid nonzero decimal digit whose source byte does not contain a plus code.

Historical Note: In the original IBM System/360 Principles of Operation (A22-6821-00), the significance indicator was called the S-Trigger. In later versions of the S/360 PoO, the term S-trigger had been replaced by the current term significance indicator.

6 of 23

The 1^st Operand

The 1^st operand comprises pattern bytes, having the following encoding:

Digit Selector (DS): X’20’
Significance Starter (SS): X’21’
Field Separator (FS): X’22’
Message byte (MB): Anything else

Depending on the pattern byte, it is updated based on its encoding as follows:

Replace with the next digit selected from the 2^nd operand, or
Replace with the fill byte, or
Remains unchanged.

The length (L) of the first operand in bytes is specified in bits 8-15 of the instruction.

The object code generated is one less than that specified in the assembler-language statement.

6

The 1^st operand of ED and EDMK comprises pattern bytes. Pattern bytes appear to be processed one by one from left to right, as follows:

The pattern byte is replaced with the zoned-decimal representation of a packed-decimal source digit from the 2^nd operand. For example, a 2^nd-operand packed-decimal source digit of 2 becomes a first-operand zoned-decimal character X’F2’, etc.
The pattern byte is replaced with a fill byte (see next slide).
The pattern byte remains unchanged.

Processing of pattern bytes is dependent on their encoding, as follows:

X’20’ is a digit selector (DS),
X’21’ is a significance starter (SS, also known as start-of-significance [SOS] ),
X’22’ is a field separator (FS), and
Anything else is a message byte.

Each of these will be discussed in the following slides.

The length of the first operand in bytes may be between 1 and 256. However, as with all SS-format instructions, the length in the L field of the instruction (bits 8-15) is one less than the true length (i.e., the value coded in the assembler-language statement).

The digit selector (DS) and significance starter (SS) pattern bytes determine the number of packed-decimal digits selected from the second operand. Thus, the actual length of the second operand varies dependent on the number of DS and SS pattern bytes in the first operand.

Note: If you look in Appendix I of the IBM z/Architecture Principles of Operation (SA22-7832) or in the IBM z/Architecture Reference Summary (SA22-7871), you will discover that the EBCDIC encodings for hex 20, 21, and 22 are called DS, SOS, and FS, respectively.

7 of 23

1^st-Operand Fill Byte

The leftmost pattern byte in the first operand is the fill byte.

When a DS or SS selects a zero digit from the 2^nd operand, and the significance indicator is off, the 1^st-operand pattern byte is replaced with the fill byte.
When a 1^st-operand pattern byte is a field separator, the field separator is always replaced by the fill byte.
When a 1^st-operand pattern byte is a message byte, and the significance indicator is off, the message byte is replaced by a fill byte.

The fill byte may any character, including a control function (i.e., DS, SS, or FS).

7

Regardless of its content, the leftmost byte of the 1^st operand is the fill byte. The fill byte is used as follows:

When a digit selector (DS) or significance starter (SS) pattern byte causes a packed-decimal zero to be selected from the 2^nd operand, and the significance indicator (SI) is off, then the DS or SS is replaced with the fill byte. This is how a packed-decimal value such as 0012345C hex can have its leading zeros replaced with a blank or a security code such as an asterisk.
When a field separator (FS) pattern byte is encountered, it is always replaced by the fill byte.
When a message byte (MB) pattern byte is encountered, and SI is off, the message byte is replaced by the fill byte. For example, if the pattern contains message bytes indicating that commas are to be inserted for every order of magnitude (i.e., every three digits), but significance has yet to be recognized, then the commas can be replaced with the fill byte.

If it is known that the first digit selected is always significant, then filling may not be applicable. In this case, the leftmost message byte may be a DS or SS, since it will not be used for filling.

8 of 23

Digit Selector (DS, 1^st-operand pattern byte)

Code value X’20’
Depending on the significance indicator, the DS pattern byte is replaced by:

The fill byte – when SI is off and the next packed-decimal digit in the 2^nd operand is zero.
The zoned-decimal representation of the next packed-decimal digit in the 2^nd operand – when either SI is on or the decimal digit is nonzero.

When a nonzero decimal digit is inserted, SI is turned on if the rightmost 4 bits of the 2nd-operand source byte are not a plus code (i.e., not hex A, C, E, or F).

8

Digit selectors are the workhorse of converting packed-decimal digits to zoned digits with ED and EDMK. A digit selector (DS) is processed as follows:

When the next available packed-decimal source digit of the 2^nd operand is a zero, and the significance indicator (SI) is off, the digit selector in the 1^st operand is replaced with the fill character. In this case, SI remains unchanged (i.e., in the off state).
When the next available packed-decimal source digit of the 2^nd operand is a zero, and SI is on, the digit selector in the 1^st operand is replaced with the zoned-decimal equivalent of the source digit (i.e., X’F0’).
When the next available packed-decimal source digit of the 2^nd operand is a nonzero value, the digit selector in the 1^st operand is replaced with the zoned-decimal equivalent of the source digit.
When a nonzero zoned-decimal value replaces the digit selector, SI is set to one except for one case. If the rightmost four bits of the source byte from which the source digit was extracted contains a packed-decimal plus code (i.e., hex A, C, E, or F), then SI is set to zero. This peculiar exception allows SI to be used when editing the final (or only) field to indicate the sign of the field, which, in turn, is used in setting the condition code.

9 of 23

Significance Starter�(SS, 1^st-operand pattern byte)

Code value X’21’
Operates identically to a digit selector (DS), except:

For a DS, the significance indicator (SI) is turned on if a nonzero source digit is processed, and the rightmost 4 bits of the source byte is not a plus code.
For a SS, SI is turned on regardless of whether the source digit is zero, and the rightmost 4 bits of the source byte is not a plus code.

SS can be used to indicate that subsequent leading zeros should be formatted as such in the 1^st operand.

9

10 of 23

Field Separator (FS, 1^st-operand pattern byte)

Code value X’22’
A field separator in the 1^st operand is always replaced by the fill byte.
The significance indicator is always turned off.

And that’s all there is to it!

10

11 of 23

Message Byte (MB, 1^st-Operand Pattern Byte)

Code value: Anything other than DS, SS, or FS.
Handling of the message byte is as follows:

When SI is off, the message byte is replaced by the fill byte.
When SI is on, the message byte is unchanged.

In either case, SI is unchanged.

Example of message bytes:

Message byte (also serves as fill byte).

40

20

6B

20

6B

20

21

20

4B

20

Message bytes (comma separators).

Message byte (decimal point).

11

12 of 23

2^nd-Operand Source Bytes & Source Digits

Variable-length signed or unsigned packed-decimal fields.
Each four bits of a source byte form a source digit
Leftmost source digit of each source byte must be a valid packed-decimal digit (0-9)

General-operand data exception recognized the left source digit of a source byte is a packed-decimal sign code (hex A-F)�

Example of multiple fields in the 2^nd operand:

Negative sign code.

Positive sign code.

Whoops!�Sign code in left digit is invalid.

31

41

59

26

53

58

97

9D

14

21

35

62

37

30

9C

00

45

77

81

B3

40

7D

1^st Field

2^nd Field

3^rd Field

12

The 2^nd operand of an ED or EDMK instruction consists of zero or more variable-length packed-decimal fields. The fields may contain either signed or unsigned packed-decimal values, and the length of the field is determined by the number of digit selectors and significance starters in the first operand.

Each byte of the 2^nd operand is called a source byte, and each 4-bit field with a source byte is a source digit. Because the field is of the packed-decimal format, the left source digit of each source byte must be a valid packed-decimal number (i.e., having the values of 0-9). If a packed-decimal sign code (hex A-F) is discovered in a left source digit of a source byte, a general-operand data exception is recognized.

When a 1^st-operand digit selector or significance starter selects the left source digit from a source byte where the right digit is a packed-decimal sign code, it effectively ends the packed decimal field (after processing the left digit). If the sign code is positive, the significance indicator is set to zero. Any subsequent 1^st-operand digit selectors or significance starters skip the sign code in the 2^nd operand and proceed to the next source byte for a source digit.

Therefore, it is prudent (though not required) that 1^st and 2^nd operands be coordinated such that a 1^st-operand field separator coincides with a packed-decimal sign code (if the 2^nd-operand field is signed).

In the examples in this slide, the first field comprises the first 15 digits of pi, but with the sign code set to a negative value. The second field is the first 15 digits of the square root of two, with a positive sign code. The third field contains an invalid sign code in the left source digit of a source byte (X’B3’). If the 1^st operand digit selector or significance starter caused this byte to be fetched, the instruction would result in the recognition of a general-operand data exception (program interruption code 0007, or an S-0C7 in z/OS-speak).

Note that values such as pi or the square root of two, when printed as a decimal value, have an implicit decimal point following the first digit. There is nothing in the packed-decimal value that reveals the location of the decimal point, so the program needs to be carefully designed to have a 1^st-operand pattern that correctly places the decimal point by means of a message byte.

13 of 23

Condition Code

The condition code is set based on the results in the rightmost (or only) edited field.

CC0: Rightmost (or only) field is zero or has zero length
CC1: Significance indicator is on

When the rightmost source byte examined contains a packed-decimal sign code, SI=1 indicates a negative result.

CC2: Significance indicator is off

When the rightmost source byte examined contains a packed-decimal sign code, SI=0 indicates a positive result.

Note: When SI is on, but the source field is unsigned, CC1 will be set.

13

Recall that the significance indicator (SI) serves two purposes:

It controls the propagation of the fill byte across message bytes and digit selectors before a significant digit is encountered or signaled by a significance starter.
It is used to set the condition code.

Also recall that when a source byte with a positive sign code is encountered, SI is set to the off state. This comes in handy when the last source byte for the rightmost edited field. The condition code is set based on (a) the length of the rightmost field, (b) whether the rightmost field is zero, and (c) the state of SI, as follows:

CC0 indicates either of the following:

The rightmost edited field does not contain any numeric digits.
The content of the rightmost edited field is zero.

CC1 indicates that the significance indicator is on. This indicates that either (a) the rightmost source byte contained a sign code that was negative, or (b) the rightmost source field was unsigned.
CC2 indicates that the significance indicator is off. This indicates that the rightmost source field is positive.

NOTE WELL: Even if you happen to think of unsigned packed-decimal fields as being positive, if the rightmost packed-decimal field of the 2^nd operand is unsigned, condition code 2 will not be set!

14 of 23

EDIT AND MARK (EDMK)

EDMK D₁,(L,B₁),D₂,(B₂) [SS-a]

DF

L

B₂

D₂

B₁

D₁

0

1

7

8

9

5

C

40

20

6B

20

6B

20

21

20

4B

20

1^st Operand Before (hex):

1

,

7

8

9

.

9

5

1^st Operand After (EBCDIC):

General register 1 points to the leftmost significant digit of the rightmost (or only) field having significance.

14

Except for the operation code (hex DF) and the mnemonic, the EDIT AND MARK (EDMK) instruction is remarkably similar to the EDIT (ED) instruction described on slide 3.

EDIT AND MARK performs the same operations as EDIT, but with one additional feature: General register 1 is updated with the address of the first significant byte in the rightmost (or only) field of the 1^st operand.

This feature is very handy for inserting an indication immediately to the left of the first significant digit, for example a currency symbol ($, £, ¥, €), credit indication, or sign. Simply decrement general register 1 by one and move in the symbol of choice to the location pointed to by GR1 (note, this decrementing and symbol insertion can be performed in one instruction with the long-displacement MVIY instruction).

WARNING: When no significant bytes are encountered in the rightmost (or only) field, general register 1 is unchanged! To prevent unexpected storage overlays or addressing exceptions in this case, the condition code should be examined to determine whether a significant result was produced (thus causing GR1 to be updated). Alternatively, GR1 could be preloaded with a legitimate address (such as the first digit selector or significance starter in the last or only field) before attempting to execute EDMK.

15 of 23

Examples of EDIT (ED) (1 of 3)

Message Byte

Digit Selector

Significance Starter

Field Separator

Edit a Value in Millionths

40

20

6B

20

6B

20

21

20

4B

20

6B

20

1^st Operand (before, hex):

1

2

3

,

4

5

6

.

7

8

9

,

0

1

2

1^st Operand (after, EBCDIC):

2

Resulting condition code:

01

23

45

67

89

01

2C

2^nd Operand (hex):

(code: P’0123456789012’)

Same Thing but with Smaller 2^nd Operand

40

20

6B

20

6B

20

21

20

4B

20

6B

20

1^st Operand (before, hex):

1

.

2

3

4

,

5

6

7

1^st Operand (after, EBCDIC):

2

Resulting condition code:

00

12

34

56

7C

2^nd Operand (hex):

(code: P’0000001234567’)

Same Thing but with 2^nd Operand of Zero

40

20

6B

20

6B

20

21

20

4B

20

6B

20

1^st Operand (before, hex):

0

.

0

,

0

1^st Operand (after, EBCDIC):

0

Resulting condition code:

00

0C

2^nd Operand (hex):

(code: P’0000000000000’)

15

This slide shows some examples of the results of executing an EDIT (ED) instruction with various 2^nd-operand source values and 1^st-operand pattern bytes. In each of the following examples, the pattern bytes are color coded as shown in the top right of the slide.

The first example shows a pattern that will format a packed-decimal value with the most significant digit representing millions, and fractional values of millionths, with orders of magnitude separated by commas and a decimal point separating whole numbers from fractions.��Note that the results contain three blanks on the left. The first blank is the fill byte; the second blank is because the first packed-decimal source digit is a zero, and significance has not yet been recognized; and the third blank is because the message byte containing the comma (X’6B’) is also suppressed due to lack of significance being recognized … yet.
The second example illustrates more fill-byte insertion on the left. In this case, the leftmost “1” would be printed regardless of the significance starter (X’21’ in the 1^st operand) since it is nonzero, and hence, significant.
The third example shows that once the significance starter is encountered, subsequent zeros will be formatted (rather then insertion of the fill byte), since the significance starter forces significance to be recognized with the subsequent source digit. Note that unlike the first two examples, where the condition code indicates a positive value was edited, the condition code in this example is zero, reflecting the content of the results.

16 of 23

Examples of EDIT (ED) (2 of 3)

Message Byte

Digit Selector

Significance Starter

Field Separator

Edit a Value with an Asterisk as the Fill Byte

5C

20

6B

20

6B

20

21

20

4B

20

1^st Operand (before, hex):

*

9

,

8

7

6

,

5

4

3

.

2

1

1^st Operand (after, EBCDIC):

2

Resulting condition code:

98

76

54

32

1C

2^nd Operand (hex):

(code: P’987654321’)

Same Thing, but with More Asterisks

5C

20

6B

20

6B

20

21

20

4B

20

1^st Operand (before, hex):

*

1

,

0

2

4

.

0

1^st Operand (after, EBCDIC):

1 (sign code ‘D’ means negative)

Resulting condition code:

00

01

02

40

0D

2^nd Operand (hex):

(code: P’-000102400’)

Same Thing, but with Lots More Asterisks

5C

20

6B

20

6B

20

21

20

4B

20

1^st Operand (before, hex):

*

1

.

9

8

1^st Operand (after, EBCDIC):

2

Resulting condition code:

00

19

8C

2^nd Operand (hex):

(code: P’000000198’)

16

This slide shows examples of using the fill byte to replace insignificant results with a non-blank character. This sort of padding is useful when adding a security character to help prevent alteration of a printed value, such as in a check or money order.

The first example shows the amount of an IRS refund check that I would like to receive this year (and next year, and the year after that).��Note that unless the first pattern byte also happens to be a significance starter or digit selector, at least one fill byte will always be produced in the result.
Example 2 shows the replacement of insignificant leading zeros – and the replacement of message bytes – with many more fill bytes.
And, example 3 illustrates the amount of taxes that I think I should be paying from now on (with security characters to make sure that the IRS doesn’t alter my check). ☺

17 of 23

Examples of EDIT (ED) (3 of 3)

Message Byte

Digit Selector

Significance Starter

Field Separator

Edit Pattern Leading Off with a Significance Starter

1

Resulting condition code:

00

06

2^nd Operand (hex):

(code: P’-00000000069’)

40

21

20

4B

20

6B

20

6B

20

1^st Operand (before, hex):

20

0

.

0

,

0

,

0

1^st Operand (after, EBCDIC):

6

9

9D

Editing Multiple Fields from a Single Packed Number

2

Resulting condition code:

12

34

56

70

04

2^nd Operand (hex):

(code: P’1234567004321’)

32

1C

40

20

6B

20

21

20

4B

20

22

20

6B

1^st Operand (before, hex):

20

21

20

4B

20

1

2

,

3

4

5

.

6

7

1^st Operand (after, EBCDIC):

4

3

.

2

1

Editing Multiple Fields from Multiple Packed Numbers

2

Resulting condition code:

12

3C

45

6C

78

2^nd Operand (hex):

(code: P’123,456,789,012’)

9C

01

2C

40

21

4B

20

22

1^st Operand (before, hex):

21

4B

20

22

21

4B

20

22

21

4B

20

22

1

.

2

3

4

.

5

6

7

.

1^st Operand (after, EBCDIC):

8

9

.

1

2

17

Here are a few additional examples:

The first example shows a pattern leading off with a significance starter. Note that the first packed-decimal zero is still replaced by the fill byte; significance does not occur until the next pattern byte following the significance starter.
Example 2 illustrates the editing of multiple fields, as indicated by the field separator (X’22’) in yellow. Note that even though the pattern bytes divide the result into two fields (with two separate recognitions of significance), the source operand consists of a single packed-decimal number.
Example 3 shows the editing of multiple fields, however in this example, each field in the 2^nd operand corresponds to a separate packed-decimal number in the first operand.

For those who have been paying attention, it should now be obvious that the digits selected by the DS and SS pattern bytes in the 1^st operand need to be carefully coordinated with the size of the packed-decimal field(s) in the 2^nd operand. A few observations:

One of the attributes of a signed packed-decimal field is that the number of source digits is always odd! This presents interesting challenges in getting the pattern bytes that produce the result to match the source bytes. The program may have to accommodate an extra fill byte in the resulting 1^st operand.
Other than setting the significance indicator (and hence, the condition code), packed-decimal sign codes in the rightmost four bits of a packed-decimal source byte are ignored.
Unsigned packed-decimal values present more flexibility – and/or more challenges – when converting into zoned-decimal results. As noted above, a packed-decimal field always comprises an odd number of source digits plus a sign code, thus a signed packed-decimal field cannot span bytes. An unsigned packed-decimal field has no sign digit; thus – at least, as far as ED and EDMK are concerned – a single byte can contain unsigned packed-decimal digits from two separate fields. (We see this in example 2, above.)

18 of 23

Examples of EDIT AND MARK (EDMK) (1 of 2)

Message Byte

Digit Selector

Significance Starter

Field Separator

Edit a Value in Millionths, Mark the 1^st Significant Digit

40

20

6B

20

6B

20

21

20

4B

20

6B

20

1^st Operand (before, hex):

1

2

3

,

4

5

6

.

7

8

9

,

0

1

2

1^st Operand (after, EBCDIC):

2

Resulting condition code:

01

23

45

67

89

01

2C

2^nd Operand (hex):

(code: P’0123456789012’)

Editing Multiple Fields from a Single Packed Number

2

Resulting condition code:

12

34

56

70

04

2^nd Operand (hex):

(code: P’1234567004321’)

32

1C

40

20

6B

20

21

20

4B

20

22

20

6B

1^st Operand (before, hex):

20

21

20

4B

20

1

2

,

3

4

5

.

6

7

1^st Operand (after, EBCDIC):

4

3

.

2

1

GR1 after

General register 1 points to the leftmost significant digit of the rightmost (or only) field having significance.

GR1 after

18

Recall a few slides ago, we indicated that the EDIT AND MARK (EDMK) instruction performed the same functions as the EDIT (ED) instruction, but with one additional feature. At the completion of the instruction, general register 1 is updated to point to the leftmost significant digit of the rightmost – or only – edited field that has significance. This slide repeats two of the preceding examples, illustrating the setting of GR1.

The first example has a single edited field where the first significant digit was the leftmost “1” in the result. The first three bytes of the result contain the fill byte because (a) the fill byte is a message byte that is propagated to the result, (b) the leading source digit of zero is insignificant, so it is replaced by the fill byte, and (c) the pattern byte X’6B’ (comma) is a message byte that is also replaced by the fill byte because no significant digits have been encountered yet. Thus, GR1 will be updated to point to the fourth byte of the first operand at the completion of the instruction.
In the second example, there are two fields being edited. General register 1 is updated to point to the first significant zoned-decimal digit of the rightmost result field; that is, the “4” in the 15^th byte of the first operand.

When editing currency values, the updating of GR1 is very handy for inserting a currency symbol immediately to the left of the leftmost significant digit. One simply needs to decrement GR1 by one, and move in a currency symbol such as $, £, ¥, or €. For example:

EDMK RESULT,SOURCE� MVIY -1(1),C’€’

So, what if no significant digits are encountered in the editing operation? In this case, general register 1 is unmodified! Therefore, if there is a possibility that the edited first operand will contain no significant digits, it is critical to account for the possibility that GR1 has not been updated (and many an addressing exception has resulted from not accounting for this possibility).

In the case of a multi-field editing pattern, if a significant zoned-decimal digit is found in an earlier (left) field, but no significance is found in the later (rightmost) field, GR1 contains the address of the last discovered leading significant digit in the result. We’ll see an example of this in the next slide.

19 of 23

Examples of EDIT AND MARK (EDMK) (2 of 2)

Message Byte

Digit Selector

Significance Starter

Field Separator

Edit a Value of Zeroes with No Significance Starter

40

20

1^st Operand (before, hex):

1^st Operand (after, EBCDIC):

0

Resulting condition code:

00

0C

2^nd Operand (hex):

(code: P’00000’)

WARNING: General register 1 is unmodified when no significant digits are discovered.

GR1 after

General register 1 contains the address of leftmost significant digit of the rightmost field having a significant digit. Because the third field is insignificant, GR1 does not point to it.

Editing Multiple Fields from a Single Packed Number

0

Resulting condition code:

12

3C

45

6D

00

2^nd Operand (hex):

(code: P’123,-456,000’)

0C

1

2

3

4

5

6

1^st Operand (after, EBCDIC):

40

20

21

20

22

1^st Operand (before, hex):

20

21

20

22

20

19

Here we see a few examples of EDIT AND MARK that do not necessarily follow the path of least astonishment:

In the first example, the 2^nd-operand source digits are all zeros, and the 1^st-operand contains no significance starter. So, the entire second operand is replaced by the fill byte.��Recall the admonition from the preceding slide. In the case where no significance is discovered, general register 1 is unmodified. So, if the program blindly decrements GR1 and attempts to use it to insert a currency symbol without accounting for this condition, really bad things may happen!
In the second example, the 1^st operand contains three pattern fields. Because the source digits selected by the right pattern-byte field are all zero – and the pattern for the right field contains no significance starter – all of the pattern bytes are replaced with the fill byte. But because the second field selected a significant digit, general register 1 is updated to point to it.

20 of 23

Programmator Caveat

Signed packed-decimal fields always contain an odd number of digits.

The rightmost 4 bits of the rightmost byte of the packed field contains the sign code.

Binary 1010, 1100, 1110 and 1111 indicate positive (1100 preferred)
Binary 1011 and 1101 indicate negative (1101 preferred)

If a signed packed-decimal field contains an even number of digits, the leftmost digit will always be zero!

P‘11235813’ generates X‘011235813C’
P‘-123456’ generates X‘0123456D’

A common mistake in generating ED and EDMK pattern bytes is to not account for this leading zero!

20

With all due apology to the Latinophiles in the audience, the title should be “Programmator Cave”, but caveat is more commonly understood. For the non-Latinophiles in the audience, the title simply reads “Programmer Beware.”

One conundrum that programmers have to deal with when formatting packed-decimal data with ED and EDMK is that signed packed-decimal data fields always contain an odd number of digits. This is because the rightmost 4-bit digit of a signed packed-decimal field is the sign code.

Sign codes for positive values are 1010, 1100, 1110, and 1111 binary (A, C, E, and F hex), with 1100 being a preferred code.
Sign codes for negative values are 1011 and 1101 (B and D hex), with 1101 being preferred.
Note that if a sign code appears in any left digit of a packed-decimal field used by ED or EDMK, the instruction will slap the programmer with a general-operation data exception (program-interruption code 0007, or S/0C7 in z/OS speak).

For the packed-decimal fields in this slide – each containing an even number of digits – the hexadecimal code contains a leading digit of zero:

Assembler code P‘11235813’ (the first few digits of the Fibonacci sequence) results in X‘011235813C’.
Assembler code P‘-123456’ results in ‘0123456D’.

When crafting the first operand of ED or EDMK, it is crucial that the programmer be aware of the number of packed-decimal digits that will be selected by digit-selector (DS) or significance-starter (SS) pattern bytes, and account for a leading zero!

21 of 23

ED and EDMK Conceptual Flow

END 🡨 OP1 + L;

LRF 🡨 0 (left);

NZD 🡨 0;

SI 🡨 0 (off);

ED & EDMK

*OP1 and�*(OP1+L) accessible

Access Exception

FB 🡨 *OP1;

SI

LRF 🡨 0 (left);

No

Yes

(left) 0

1 (right)

LRF

PB 🡨 *OP1;

PB == DS�or

PB == SS

PB == FS

Yes

SI 🡨 0;�NZD 🡨 0;

Yes

No

1

0

*OP1 🡨 FB;

OP1++;

OP1 > END

NZD

No

Yes

Exit CC0

SI

1

Exit CC1

0

1

Exit CC2

RD > 9

Yes

*OP2 accessible

Access Exception

No

SB 🡨 *OP2;

SD 🡨 SB >> 4;

RD 🡨 SB & 0x0F;

OP2++;

SD > 9

General Op. Data Exception

Yes

LRF 🡨 LRF ^ 1;

SI

0

1

SD

0

>0

For EDMK, GR1 set to OP1.

*OP1 🡨 FB;

*OP1 🡨 SD | 0xF0;

Get Next Source Digit

Handle DS or SS Pattern Byte

No

SD 🡨 RD;

SD

>0

NZD 🡨 1;

0

PB == SS

Yes

No

RD == PLUS

SI 🡨 1;

Yes

No

SI 🡨 0;

A

Notes:�A. When the pattern byte is a message byte (i.e., not a DS, SS, or FS) and the significance indicator is on, � the pattern byte is effectively unchanged. A store of unchanged data must occur for change-bit setting� and PER purposes.

B. This is a simplification of the operand-2 access checking. On all modern machines, all accessed bytes of� the second operand are assured to be accessible before any byte of operand 1 is stored.

B

21

This slide presents a conceptual flow chart depicting the operation of the EDIT and the EDIT AND MARK instructions. The statement syntax is sort of C-ish (and – with all due apology to those skilled in C – sort of not C-ish). The following slide contains an explanation of the symbols used in this slide.

The flow on the left of the chart represents the fetching of pattern bytes, the processing of field separators (FS) and message bytes (MB), the looping through the first operand, and the final setting of the condition code.
The shaded area in the middle of the chart represents the processing of fetching the next source byte from the 2^nd operand, the recognition of a general-operand data exception if the source byte is shazbot (i.e., if the left digit is a sign code), and separating the source byte into source digits (SD and RD).
The flow on the right of the chart represents the handling of source digits that are processed as a result of either a digit selector (DS) or start-of-significance (SS) pattern byte.

Note, this is a conceptual flow. Actual processing is a bit trickier …

… recall that the length of the 2^nd operand is dependent on the digit selectors and significance starters in the 1^st operand; thus, at the beginning of the instruction’s execution, the length of the 2^nd operand in unknown. However, the length of the 2^nd operand will never be longer than that of the 1^st operand; so, the length of the 2^nd operand will never be more than 256 bytes.

If the address of the 2^nd operand is close to an access boundary (i.e., within 256 bytes of the end of a page, segment, or region) or close to a protection boundary (i.e., storage key, DAT protection or access-list protection), then there’s the possibility that part of the 2^nd operand might be inaccessible. In this case, modern CPUs will perform a dry run of the instruction to determine whether it can be successfully completed before any 1^st-operand byte is modified. Without the dry-run feature, an access exception found in the 2^nd operand after 1^st-operand bytes have been modified would necessitate termination (rather than suppression). To find out more about why termination is really, REALLY bad, read up on “Instruction Ending” in Chapter 5 of the z/Architecture Principles of Operation.

22 of 23

Explanation of Symbols Used in Conceptual Flow

🡨 Assignment
+ Addition
++ Increment
& Logical AND
| Logical OR
^ Logical exclusive OR (XOR)
* Dereferencing of pointer
CC Condition code set at instruction completion
DS Digit selector (pattern byte X’20’)
END Pointer to the last byte of the 1^st operand
FB Fill byte (1^st byte of 1^st operand)
FS Field separator (pattern byte X’22’)
GR1 General register 1
L Length of the 1^st operand from the instruction text (zero based)
LRF Left / right flag (0=left; 1=right)
NZD Non-zero-detected flag (0=nothing yet; 1=nonzero detected)
OP1 Pointer to the next byte of the 1^st operand
OP2 Pointer to the next byte of the 2^nd operand
PB Pattern byte from the 1^st operand
PLUS Packed-decimal positive sign code (i.e., hex A, C, E, or F)
RD Right digit from the source byte
SB Source byte from the 2^nd operand
SD Source digit from the source byte
SI Significance indicator (0=off, 1=on)
SS Significance starter (pattern byte X’21’)

22

23 of 23

Lessons Learned

ED and EDMK provide extremely powerful capabilities for efficiently formatting signed or unsigned packed-decimal data

Replacing insignificant leading zeros and message bytes with a fill character.
Adding formatting characters such as magnitude and decimal characters
Processing multiple fields

All in a single instruction!

EDMK provides the indication of where significance is detected in the result (if it’s detected at all).

23