Guidelines for writing mapping strings


Much like Regular Expressions, mapping strings, with their various commands and operands, can be somewhat cryptic at times, and for all but the simplest cases they may not be something that will easily “roll off the tip of your tongue”.   Naturally, the more complex your mapping or modification operations are, the more complex the mapping string will be.  You may need to reread the documentation (perhaps each time you use it), and plan out in advance what these strings will contain.


You may benefit by saving off some mapping commands you have found useful, along with a few descriptive notes, into a text file to have them handy, like having a “cheat sheet”.  That way, if you need to use them again, you can refer to your notes instead of always having to reread this documentation.  Or, you can specifying an external mapping string item of SV to fetch a SET variable containing part of a mapping string.  You can also use an SPFLite SET variable to define an entire mapping string, and then you would specify it on your CHANGE command with an = equal sign followed by the name of the SET variable.


You can look at the provided examples to help understand how mapping strings are written; if one is close to what you need, you may be able to copy and tailor it.  When working with your own data, there are a few ways to go about defining a mapping string.  For short data, the simplest way may be to just write some sample data on a piece of paper, drawing lines where various substrings of your data are located, and counting the columns.  Then, write down each ‘piece’ of your data as you want it reformatted, in left-to-right order, so that each ‘piece’ is an item in a mapping string, as described above.


For longer data, you can use SPFLite to help.  If you highlight a string on a line, you will see its length displayed on the status line, like Len 8.  If you place your data on a line by itself, left-justified on column 1, you will see the length of the line on the status line when the cursor is on that line of data,  like Line Len 8.  Be certain the line is trimmed to sure you don’t count any trailing blanks.  You can trim a line of data by using the TR line command.  The virtual highlighting pens feature of SPFLite may also be useful.


You also have the L/C display on the status line, which shows the Line number and Column number where the cursor is located.  If your data is on line 125, you will see a display of L 000125 C 8 when the cursor is on the last column your data.


Finally, you can issue the COLS line command to show you column positions.


Bear in mind that the “column numbers” or “column ranges” in a mapping string are the relative positions of your data.  Those numbers have nothing to do with where (what actual column positions) on a data line that your data is found in the course of executing a CHANGE command.  You must visualize your data as if it were left-justified on column 1 of a line, for purposes of numbering the positions, even though your data may actually appear anywhere, in any columns of a line.


Remember that many mapping commands are what is termed “modifying commands”.  That means they are designed to alter the contents of the result string.  To use such commands on data that is in the source string, you have to first copy some or all of the source string to the result string.  The easiest way to do that is with a column-copying command of 1+ at the beginning of your mapping string.  You will see examples in the documentation that use this technique.  However, for many commands (but not all), the auto-reference and auto-copy features mean that oftentimes you won’t need to use a column reference of 1+ to reference or copy the entire source string, because it will be implied and will happen automatically.


You may come across cases where a single mapping operation is not powerful enough to do what you need. When that happens, it’s possible you could do part of the mapping in one pass, and in the process, insert or append to the result string some special character of your choosing as a “marker”.  Then, you would go back with another CHANGE command that looked for strings containing that special “marker” character, and do the remaining data reformatting that you were unable to complete in the first pass – either with another M string or perhaps a conventional string of type C, T or X.  


To improve performance, and limit the second pass to only those lines affected by the first pass, you could use Command Chaining techniques involving a “Z tag” of :ZF on your second CHANGE command.  See the Help article Working with Command Chaining for more information.


When using this technique, be mindful of what characters have special meaning in a Picture or Regular Expression string if you use them.  (In some cases, you might need to escape certain special Picture characters with a \ backslash.)  In Pictures, you may be able to use () parentheses, or symbols such as ¢ £ or  which are uncommon but are treated as ordinary data characters in these strings.  You can also use the single and double “word processing quotes” in the ANSI range of X'91' to X'94' as delimiters.  These are just some possibilities for you to explore.  The KEYMAP facility can be used to map any suitable characters to the desired keys so you can have them readily available to type.


When even such advanced mapping-string techniques are not enough for your needs, an execute-macro string, also known as an “E string”, may be useful.


Finally, as with any other aspect of SPFLite, if you have questions or need help with this feature, the SPFLite online forum is available to assist you.  Of course, if you do that, the first question we will ask is, Have you read the documentation?  So be sure to start with that important first step.




Examples


For examples of mapping string usage, see Command Specific Syntax and Examples for more information.




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