External mapping string item – SV

External mapping string item – SV


Because mapping strings can sometimes be long and intricate to specify, you may benefit from saving a copy of them in a text file, to have them ‘on hand’ and available if you need to use them again.  However, you would still need to cut-and-paste such a string from your text file into the mapping command that you issued, which may not be the most convenient thing to do.


You could also define entire mapping strings as SET variables.  When you did that, you would put everything, including the M type code, as the value of the variable, and then reference that by name on the command like with a leading = equal sign.  When preparing such SET variables, you will find it easier to issue a plain SET command, and then type in your values in the Set Edit screen, rather than typing it all on the primary command line.


The external mapping string facility described here would be used when you only want “pieces” of your mapping string replaced by outside definitions rather than the entire mapping string.  By using an external mapping string, you have the benefit of maintaining a copy of your frequently used mapping strings without having to do a cut-and-paste of them.  When you do this, you can store your external strings as SPFLite SET variables.



Syntax of an external mapping string item:


SV   symbol-name


SV:


Introduces the external mapping string item.  SV directs the mapping-string processor to use an SPFLite SET variable as the source for further mapping command items.


Symbol-name:


A quoted-string operand that defines the name of the variable to be referenced.  It is an error if the variable in question is not defined.  It is not an error if the variable in question exists but has a text value of zero length or only contains blanks.  That is a technique you could use to make certain commands like “no operation” commands, especially if you have ‘nested’ these commands.  It would a technique to selectively enable or disable certain commands.  See comments below about nesting.


If for some reason defining value that is empty on the right-hand side of the = equal sign is a problem, you can use a lone ; semicolon, which is treated as equivalent to a blank when unquoted, and is ignored.


The symbol name cannot be missing or blank or contain any characters other than letters, digits or underscores.


When you specify a symbol name, a prefix is added to the name you supply.  If you issue a mapping command of SV'ABC',  the SPFLite SET variable that is searched for is  MAPSTR.SV.ABC.


Once the mapping commands found in the mapping variable are processed, the original mapping commands after your SV command resume where they left off.  In that sense, the SV mapping commands are like #INCLUDE statements in a programming language.


It is permitted for SV commands to nest, up to 10 levels deep.  It is an error to refer to these variables in a way that is “recursive”, whether directly or indirectly.  The mapping string logic will detect a recursive reference and halt the processing with an error message if this occurs.  Recursion is defined as any SET variable being referenced again before its content has been fully “consumed”, or if for any reason the nesting level exceeds 10.


When you use the SPFLite SET facility, smply quote the value exactly as you want to store it.  For example, if you want to make a SET name for ABC, and define it as the mapping command RA'ABC=DEF', issue this at the primary command line:


       SET MAPSTR.SV.ABC = "RA'ABC=DEF'"


When you use a SET variable defined this way, your mapping string would reference it with an item of SV'ABC'.



Created with the Personal Edition of HelpNDoc: Easy EPub and documentation editor