The $PIECE function returns a substring delimited by a specified string delimiter made up of one or more characters. In M, $PIECE() returns a logical field from a logical record.
The format for the $PIECE function is:
$P[IECE](expr1,expr2[,intexpr1[,intexpr2]])
The first expression specifies the string from which $PIECE() takes its result.
The second expression specifies the delimiting string that determines the piece "boundaries"; if this argument is a null string, $PIECE() returns a null string.
If the second expression does not appear anywhere in the first expression, $PIECE() returns the entire first expression (unless forced to return a null string by the second integer expression).
The optional first integer expression (third argument) specifies the beginning piece to return; if this argument is missing, $PIECE() returns the first piece.
The optional second integer expression (fourth argument) specifies the last piece to return. If this argument is missing, $PIECE() returns only one piece unless the first integer expression is zero (0) or negative, in which case it returns a null string. If this argument is less than the first integer expression, $PIECE() returns a null string.
If the second integer expression exceeds the actual number of pieces in the first expression, $PIECE() returns all of the expression after the delimiter selected by the first integer expression.
The $PIECE() result never includes the "outside" delimiters; however, when the second integer argument specifies multiple pieces, the result contains the "inside" occurrences of the delimiter.
$PIECE() provides a tool for efficiently using values that contain multiple elements or fields, each of which may be variable in length.
Applications typically use a single character for a $PIECE() delimiter (second argument) to minimize storage overhead, and increase efficiency at run-time. The delimiter must be chosen so the data values never contain the delimiter. Failure to enforce this convention with edit checks may result in unanticipated changes in the position of pieces within the data value. The caret symbol (^), backward slash (\), and asterisk (*) characters are examples of popular visible delimiters. Multiple character delimiters may reduce the likelihood of conflict with field contents. However, they decrease storage efficiency, and are processed with less efficiency than single character delimiters. Some applications use control characters, which reduce the chances of the delimiter appearing in the data but sacrifice the readability provided by visible delimiters.
A SET command argument can have something that has the format of a $PIECE() on the left-hand side of its equal sign (=). This construct permits easy maintenance of individual pieces within a string. It also can be used to generate a string of delimiters. For more information on SET $PIECE(), refer to SET in the "Commands" chapter.