Character-move item – M



You can use the Move command to move data from one location to another within result string, when you want to rearrange the result string, or when the standard default of appending values to the end of the result string is not what you need.  The Move command, along with the Delete command D allow you to treat the result string as a sort of “scratch pad area” where you can arrange the layout of this string in ways that are more flexible than just appending values to the end, as most mapping commands do.


Syntax of a character-move item:


       M  destination-reference  column-reference  


M:


Introduces the character-move item.


Column-reference:


Defines the columns within the result string where the moved data is coming from.  After being moved, the data in these columns is deleted.  This can be any standard column reference operand including end relative notation with an * suffix.  You cannot specify a column of 0 or \0.  Because data always moves from one place to another within the result string, the column reference implicitly uses dot notation even if you don’t specify an actual dot (because this is a modifying command).    The column reference cannot be omitted.


Destination-reference:


A quoted string value that specifies the location where the moved data is going to within the result string.  The value can be any standard column reference operand including end relative notation with an * asterisk suffix, or a lone * asterisk, in quotes.  Depending on how this is specified, the move operation may involve either an insertion of data or a replacement of data.  You cannot specify a column of 0 or \0.  The destination reference cannot be omitted.


Because all mapping-string commands uses a fixed format syntax, which does not support having two column reference operands in a single command, it is necessary to put the destination reference into the string operand.  


Within that string value, the destination reference has the same syntax as a column reference does, with the addition of a lone * notation:


       first  [  -  second  ]

|        first  [  -  second  ]   *

|        first    /  second        *

|        first    \  second        *

|        *


In the destination reference string, do not include any spaces or other characters other than what is allowed by the syntax.  The destination reference is handled as follows:


  1. When you specify a single column as first, the moved data is inserted at that point in the current result string, and the remaining data is pushed to the right.   For example, if you specified a destination column of '5', the moved data is inserted at position 5 of the current result string, and whatever data was formerly located in positions 5 and after is pushed to the right.  This means that a single column value specifies where the moved data goes before.  For example, a single column of '1' means the moved-in data is inserted before column 1 of the existing data.


  1. When you specify a column range as first-second, it defines a column range within the result string where the data is to be moved into, with the former data in those columns being deleted.  For example, if you specified a destination column range of '4-5', the moved data is inserted into positions 4-5 of the current result string, deleting whatever formerly was located in positions 4-5, and whatever data was formerly located in positions 6 and after is pushed to the right.


  1. To replace a single column position, you must do so with a destination column range like '5-5', because a simple column of '5' means insertion, not replacement.


  1. Regardless of how you specify the destination reference and the column reference values, you do so from the standpoint of how the original source string appears, before you alter it with the Move command.  That is, as data is being inserted and deleted, it does not “throw off” the original column numbering of data in the source string.


  1. If you specify a column or column-range with a trailing *, like '2*' or '5-1*', it is an end-relative column reference, as usual.  You may also specify mixed-mode end-relative column notation.


  1. If you specify the destination as a lone '*' it means the data is moved to the right of (at the end of) the last position in the current result string.  This lone '*' feature only pertains to the destination for a Move command; it is not a general column reference notation that you could use on other mapping commands.


  1. If you specify a lone '*' to append data to the end of the result string, but the data you requested with the column reference is already located at the end of the  result string, it is not an error, but no change will take place.


  1. The destination reference and the column reference columns must not overlap, or else an error is reported, and no modification of the result string will occur.


  1. As with other commands, if the column reference is outside the bounds of the actual value of the result string, the selected columns will be adjusted if there is at least some overlap to the actual value; if there is no overlap at all, it is considered an out-of-bounds reference, and no change will take place.  For instance, if the result string is length 10, and you specify a column reference of 9-15, this will be adjusted to a range of 9-10 , because that is where the column reference overlaps the actual data.  If you specified a column reference of 12-15 for the same data, the Move command will be suppressed, since there is no overlap.  Such a condition is not treated as an “error” but no action is taken, and the result string is not modified.


  1. Similarly, a column range destination reference is likewise adjusted to be within the bounds of the actual data.  A single-column insertion-point destination reference is not adjusted; it must reference a valid column within the current result string (or be specified as '*') or else the Move command will not be performed.  After these adjustments are made, there must be no overlap between the destination reference and the column reference columns.


  1. Because of the preceding, if you have a real need to move data to a position beyond the current length of the result string, you must first extend its size.  That may be done with any command code that puts data in the result string.  An obvious choice to do that would be to add blanks to the end, using the Pad Right command (PR).  You can also insert literal text to extend the size of the  result string.


As with regular column reference operands, the column reference and the destination reference can reference columns of data in reverse order, causing the data order to be inverted.  SPFLite will not prevent you from reversing the order in either place, or even doing so in both places, which would cancel out the character reversal.  This is not considered an error, but such a double-reversal would serve no purpose.  You have to understand the intent of your move operation and properly specify these operands to meet your requirements.


Example 1:   Suppose your source string was "One/\TwoXyz".  


A mapping string of M"M`5`9-11" would do the following:









Example 2:   Again, suppose your source string was "One/\TwoXyz".  


A mapping string of M"M`9-11`4-5" would do the following:









Example 3:   Suppose your source string was "One/\Two" and you wish to insert "***" in the middle, but there is no "***" currently in your result string.  You can do this by inserting a "***" literal into the result string, and moving it to the desired location.  


This procedure cannot rely on the auto copy feature of Move, since both the original source string and the "***" have to already be in the result string before the Move command is issued.  For this process to work, we must first explicitly copy the source string into the result string, then insert the "***"  literal, and finally issue the Move.


This is a good illustration of why the auto copy and auto references features, as convenient as they are, cannot be relied for in every situation.  It’s important for you to understand the “data flow” involved, to make sure you will get the results you need.


A mapping string of M"1+ `***` M`5`9-11" would do the following:










Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator