num-var = Set_Msg([rc-num,] msg-str [,msg-str] ...)

Operands:

[rc-num]

this optional operand provides thee numeric return code you wish SPFLite to use for the success of this macro invocation. If the operand is omitted, then 0 (zero) is assumed.


The conventions for these return codes are:


RC=0 for success

RC=8 when a failure occurs


There are predefined symbols for these values. OK is the same as 0; and FAIL is the same as 8.


To avoid issues with future versions of SPFLite, only the values 0 and 8 (or their symbolic equivalents of OK and FAIL) should be used as return code values.


msg-str

a string containing the text of the message to be issued. When multiple strings are provided as operands, they will be concatenated together with a single blank between the operands.

Returns:

The rc-num value is returned. The value of msg-str is what will be returned by the next Get_Msg$ call.

Special Notes:

If a message is issued with rc non zero, SPFLite will prefix it with "RC=8: "


Because the RC operand is optional, simple success messages can be issued with only the text string operand. For example:

Set_Msg("Normal completion")

is functionally equivalent to:

Set_Msg(OK, "Normal completion")


It is important to understand that RC and message values passed back by other functions (like Get_Line$, for instance) are not automatically passed through to the edit user, even when the RC value is non-zero, signifying a warning or error condition was detected. You must explicitly call Set_Msg yourself if you wish a message to be displayed back to the user once the macro completes execution.


If Set_Msg is followed by any other SPFLite-provided function which itself sets the RC and message values, the values set by Set_Msg will be overridden. If it is your intent to use Set_Msg to pass back a message to the edit user (yourself) that appears on the edit screen, the call to Set_Msg should be the last function you call before issuing a HALT statement. (Or use the HALT statement itself to issue the RC and message string)

Created with the Personal Edition of HelpNDoc: Full-featured Kindle eBooks generator