How a mapping string is specified

Mapping strings are defined with a string type code of M.  As with all SPFLite strings, this code may appear at the beginning or at the end of the string, as  M'xxx' or 'xxx'M.  The M is case-insensitive.  Inside this string, blanks outside of inserted-text literals are ignored other than as delimiters.  However, the M string cannot be entirely blank or zero-length; this would imply that the string was to perform no mapping operation at all.  An empty M string is reported as an error.

A mapping string must have at least one valid command code or column reference (even if that command does not happen to alter the source string).  It is not an error to specify a valid mapping string that does not happen to result in a data change to the contents of your source string.  In addition, any time you issue a mapping string that contains a syntax error or other problems, your original source data will not be changed.

A mapping string is a quoted string value containing one or more mapping items.  Mapping items must be delimited from each other by one or more blanks.  An individual mapping item, including any optional command codes, string operand and/or numeric operands, must not have any embedded spaces or other characters not shown as part of the syntax, unless those are within a quoted string operand.

When an item references character positions that don't exist in the particular found string, they effectively map to null (zero length) character values.   For example, if you try to use a mapping string to select column 5 from a data value, but the value is only of length 4, it is not an error, but no value is selected for the absent column.  The request to do that part of the mapping is simply ignored.  The way this is handled is of particular importance when using a Regular Expression (a type-R find-string) to locate data, because a Regular Expression may be used to locate strings of varying lengths.  See the Examples in the Quick Reference for more information.

When certain kinds of items are preceded by a \ backslash, it reverses the order of the result string.  The \ backslash must be immediately followed by a number, but must itself occur at the beginning of the mapping string or be preceded by a delimiter.   (That is, you cannot run two numbers together with a backslash between, like "12\45+".  This must instead appear as "12 \45+" to make your intentions clear.)  See the discussion below for details.

Column-range operands can accept a special  / or \ punctuation as part of mixed-mode end-relative notation, discussed next.

Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool