Introduced in the 1977 ANSI M[UMPS] language standard.

This function returns a substring of the value passed as a parameter.

SET X="ABC*DEF"

Reference		Value
$PIECE(X,"*",1)		"ABC"
$PIECE(X,"*",2)		"DEF"
$PIECE(X,"*",3)		"" (empty string)
$PIECE(X,"B",1)		"A"

SET Y="B"

Reference		Value
$PIECE(X,Y,1)		"A"
$PIECE(X,Y,2)		"C*DEF"
$PIECE(X,"/",1)		"ABC*DEF"

SET X="A.B.C.D"

Reference		Value
$PIECE(X,".",1)		"A"
$PIECE(X,".",2,3)		"B.C"
$PIECE(X,".",1,100)		"A.B.C.D"
$PIECE(X,".",-5,2)		"A.B"
$PIECE(X,".",3,2)		""
$PIECE(X,"",1,100)		""

Addition in the 1984 ANSI M[UMPS] language standard.

It is allowed to specify a reference to $PIECE on the left hand side of the equal sign in a SET command.

SET ^DATA("SUB")="11^22^33^44^55"

Reference		Value
SET $PIECE(^DATA("SUB"),"^",3)=123		"11^22^123^44^55"
SET $PIECE(^DATA("SUB"),"^",3,4)="three^four"		"11^22^three^four^55"
SET $PIECE(^DATA("SUB"),"^",3)="a^b^c"		"11^22^a^b^c^four^55"
SET $PIECE(^DATA("SUB"),"^",2,4)=""		"11^^c^four^55"

SET X="This is an test"

Reference		Value
SET $PIECE(x," ",3)="a"		X="This is a test"
SET $PIECE(x," ",2,3)="was no"		X="This was no test"
SET $PIECE(x," ",3)="a"		X="This was a test"

KILL ^X
SET ^X(1,2,3)=9
SET ^X(1,2)=7
SET $PIECE(^(2),";",3,^X(1,2,3))=6
WRITE ^(2)
Let's trace the order of evaluation, and see what happens to the naked indicator:
SET ^X(1,2,3)=9
naked indicator is ^X(1,2,
SET ^X(1,2)=7
naked indicator is ^X(1,

fetch ^X(1,2,3); naked indicator is ^X(1,2,
fetch ^(2) = ^X(1,2,2), which is 'undefined' (error: M7)

So, let's resolve that problem:
KILL ^X
SET ^X(1,2,3)=9
SET ^X(1,2,2)=8
SET ^X(1,2)=7
SET $PIECE(^(2),";",3,^X(1,2,3))=6
WRITE ^(2)
Now that all referenced variables are defined, the command is evaluated
as:
SET $PIECE(^X(1,2,2),";",3,9)=6
so that the value of ^X(1,2,2) becomes "8;;6"

SET ^X("Y")=1
SET $PIECE(^X("Y"),";",2,1)=0
WRITE ^X("Y")
will produce the value 1. Because in the SET $PIECE, the until value is less than the from value, no information is changed, and the naked indicator is unaffected.

Examples with naked references:

$PIECE(VALUE,STRING)
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1,
SET ^(3,4)=$PIECE(^(5,6),^(7,8))
; 1. fetch ^(5,6) = ^ABC(1,5,6)
; 2. fetch ^(7,8) = ^ABC(1,5,7,8)
; 3. store ^(3,4) = ^ABC(1,5,7,3,4)
; Naked indicator is now: ^ABC(1,5,7,3,

$PIECE(VALUE,STRING,PIECE)
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1,
SET ^(3,4)=$PIECE(^(5,6),^(7,8),^(9,10))
; 1. fetch ^(5,6) = ^ABC(1,5,6)
; 2. fetch ^(7,8) = ^ABC(1,5,7,8)
; 3. fetch ^(9,10) = ^ABC(1,5,7,9,10)
; 4. store ^(3,4) = ^ABC(1,5,7,9,3,4)
; Naked indicator is now: ^ABC(1,5,7,9,3,

$PIECE(VALUE,STRING,FROM,TO)
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1,
SET ^(3,4)=$PIECE(^(5,6),^(7,8),^(9,10),^(11,12))
; 1. fetch ^(5,6) = ^ABC(1,5,6)
; 2. fetch ^(7,8) = ^ABC(1,5,7,8)
; 3. fetch ^(9,10) = ^ABC(1,5,7,9,10)
; 4. fetch ^(11,12) = ^ABC(1,5,7,9,11,12)
; 5. store ^(3,4) = ^ABC(1,5,7,9,11,3,4)
; Naked indicator is now: ^ABC(1,5,7,9,11,3,

SET $PIECE(VALUE,STRING,FROM,TO)=VALUE
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1,
SET $PIECE(^(3,4),^(5,6),^(7,8),^(9,10))=^(11,12)
; 1. fetch ^(5,6) = ^ABC(1,5,6)
; 2. fetch ^(7,8) = ^ABC(1,5,7,8)
; 3. fetch ^(9,10) = ^ABC(1,5,7,9,10)
; 4. fetch ^(11,12) = ^ABC(1,5,7,9,11,12)
; 5. if ^ABC(1,5,7,9,10) < ^ABC(1,5,7,8) or
; if ^ABC(1,5,7,9,10) < 1
; don't store, naked indicator is ^ABC(1,5,7,9,11,
; else continue
; 6. fetch/store ^(3,4) = ^ABC(1,5,7,9,11,3,4)
; Naked indicator is now: ^ABC(1,5,7,9,11,3,

This document is © Ed de Moel, 1995-2005.
It is part of a book by Ed de Moel that is published under the title "M[UMPS] by Example" (ISBN 0-918118-42-5).
Printed copies of the book are no longer available.

This document describes the various operators that are defined in the M[UMPS] language standard (ANSI X11.1, ISO 11756).

The information in this document is NOT authoritative and subject to be modified at any moment.
Please consult the appropriate (draft) language standard for an authoritative definition.

In this document, information is included that will appear in future standards.
The MDC cannot guarantee that these 'next' standards will indeed appear.