When you request a string to be mapped, you are taking data from a source string and using it to create a result string.  The mapping string can be thought of as a list of ‘commands’ or ‘instructions’, which are operated upon in left-to-right order. These instructions, or mapping items, consist of column ranges, command codes, and optional string and numeric operands, and are described below.

Visually, think of it like this:

       “source string”    { mapping items … }    “result string”

When the mapping operation begins, SPFLite will initially set the result string to a ‘null’ (zero-length) value. The result string is then subsequently changed as a result of the mapping commands you specify.

You may reference the source string using as many commands as you wish. As you do, each successive command will update the contents of the result string. However, the source string itself is never changed, and may be thought of as a constant, read-only value.

Just to clarify this, the source string is essentially an “input parameter” to a “mapping function”. The mapping function does not change this input parameter during the course of its operation while interpreting your mapping commands. That means you can refer to the source string multiple times with multiple mapping items, and the contents of the source string always retains the original string found by the CHANGE command. Once you have created your result string by specifying one or more mapping items, that result string replaces the found string in your data file.

For example, in the command noted above, CHANGE P'@@@@' WORD M'4-1', if the CHANGE command finds the string ABCD, that string is the source string for the duration of whatever mapping commands you issue within your M string. The source string never changes from being ABCD, since that is an “input parameter” to the mapping process. The “output parameter” from the mapping process is your result string.  That output parameter is then sent back to the CHANGE command processor to complete the CHANGE process, by replacing your original data of ABCD with DCBA.

Each column-reference selects and copies data from the source string and places it in the result string, successively appending the selected values on the right side of it, to produce an updated version of the result string. These are known as copying commands.  Each mapping item generally causes the result string to built up and get longer and longer until the final result is produced. (A few operations are an exception to this, because they may make the string shorter or update it in place.)

Some operations such as case alteration, alignment or trimming, operate on and modify the result string as a whole, as it exists as of the point where the operation in the mapping string is reached.  These  are known as modifying commands.  Thus, it is possible, for example, to “trim” the result string by a trimming command in the middle of the mapping string, and then go on to make the result string longer with additional mapping items after that.

Mapping items which are modifying commands do not use or reference the contents of the source string, but only the result string.  For example, suppose you had a source string of “abcd”, and applied a mapping string to it of M'1-2 UC 3-4'. This would work as follows:

  • Columns 1-2 of the source string are selected as “ab”. This value is copied to the result string, which is initially empty. The result string now contains “ab”. (Technically, the string “ab” is appended to a null result string, resulting in “ab”, but the effect is the same as if it were simply copied.)

  • The case alteration command UC is applied to modify the current result string. The result string now contains “AB”  

  • Columns 3-4 of the source string are selected, “cd”. This is copied and appended to the end of the result string, which at this point had “AB” because of the prior UC command. The final value of the result string is now “ABcd”.

In some cases, if you specify a column-range on a command code that is outside the range of data columns or your source string, or you have otherwise specified your command improperly, no change will be performed on your data. If you issue a CHANGE command with an M string, but nothing seems to be happening, check your data and your M string to see if you have specified it correctly. Also, check to see if your CHANGE command has produced a mapping-string error message, which may help you to identify and correct the problem.

If you have a legitimate reason to attempt to access column positions that don't (yet) exist in your source string, the best way to achieve this may be to first pad the data to the desired length (likely with spaces), and then proceed with any additional modifications to your data that you need. You cannot pad the source string itself, but you can pad a copy of it in the result string.

Created with the Personal Edition of HelpNDoc: Generate Kindle eBooks with ease