num-var = SPF_Cmd(cmd-str [,cmd-str] ... )


Operands:

cmd-str

the SPFLite primary command you wish executed. When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.


Returns:


RC will be set to the return code issued by the command. This value will also be returned in num-var. Msg$ will be set to whatever message is issued by the command.


Special Notes:


The cmd-str expression is passed as a primary command to SPFLite


Within the cmd-str, all line references should be entered using the dotted prefix. e.g. the numeric values should be normal line pointers (in string format),  preceded by a dot. Line 12 should be specified as .12 and not just 12


The dotted notation is referred to as "temporary line labels" or "line number pseudo-labels", since this notation is an extension to standard ISPF label syntax. 


See the section, "Line Labels: Temporary Line Labels, also known as Line-Number Pseudo Labels" in Working with Line Labels in the main Help documentation, for more information.


Because SPFLite primary commands do not deal with line pointers, any command expression string you create must contain line numbers and not line pointers. If you are working with a line pointer, you must ensure that the line pointer is both valid and a pointer to a data line, and then convert that line pointer to a line number; otherwise the command you create will not work. You can use the Is_Data function to confirm that a line pointer is valid and points to a data line, and Get_LNUM is used for the conversion.


For example, if you had a variable myLptr containing a valid line pointer value that points to a data line, and you wanted to build a DELETE command to delete that line, an SPF_CMD call to do that would look like this:


SPF_CMD("DELETE ." + TSTR$(Get_LNUM(myLptr))) 


If you wish to use a Line Pointer directly, rather than convert it to a Line Number, you would use the ! exclamation-point notation instead of the . dot notation. The same command above could be specified as


SPF_CMD("DELETE !" + TSTR$(myLptr))


to achieve the same thing. This ! exclamation-point notation works only inside of macros, and only for the SPF_CMD function. When you use this technique, you must be certain that the line pointer value used is for a data line and not for a special line. Otherwise, the command passed to SPF_CMD will not be executed, and the function will return RC = 8.


Note:  Be aware of the difference between concatenating strings via macro syntax and concatenating strings using the multiple operand support in SPF_Cmd.


Example:

   SPF_Cmd("DELETE !" + TSTR(myLptr))

would generate a command of:

   DELETE !5


While:

   SPF_Cmd("DELETE !", TSTR(myLptr))

would generate a command of:

   DELETE ! 5


Note the 2nd version has added a blank separating the SPF_Cmd operands, which is NOT what is desired.

Created with the Personal Edition of HelpNDoc: Make the switch to CHM with HelpNDoc's hassle-free WinHelp HLP to CHM conversion tool