API
@-Formulas
JavaScript
LotusScript
Reg Exp
Web Design
Notes Client
XPages
 
Using UpdateFormulaContext
Someone recently asked about forwarding a document and setting the subject on the mail to be forwarded. In Notes 6 a new @-function was added which makes this a very simple task.

The new formula is @UpdateFormulaContext, and all it does, in lay terms, is switch where the code is running. For example, if you compose a document, normally the code would continue to run where you were before the document was composed. But using the new @-function tells the Notes 6 client that the code should now run in the composed document.

So, here's some code that can be placed in an action button. It will forward the document and set the subject on the forwarded message.

@Command([MailForward]);
@UpdateFormulaContext;
@SetField("Subject"; "This is the subject")

Since the formula was introduced in Notes 6, if you have a mixed environment of Notes 5 and Notes 6 clients, you can prevent any errors in the Notes 5 client by forwarding the message and then exiting if the user has Notes 5. The subject won't be set, but the user won't get an error message, either. That could be accomplished by code similar to this:

@Command([MailForward]);
@If(@TextToNumber(@Version) < 184; @Return(""); 0);
@UpdateFormulaContext;
@SetField("Subject"; "This is the subject")

The check for the version being less than 184 will stop the rest of the code from running if the user has Notes 5. So the message will be forwarded, but the code will stop there.

Here is the excerpt from the Notes 6 Help on @UpdateFormulaContext:

Updates the context of a formula to the Notes client window currently being accessed by the code. For example, if the code accesses a new form called "Response" by using @Command([Compose];"Response"), @UpdateFormulaContext switches the context of the formula to this new form. Any subsequent functions in the code execute in the context of the Response document, not the current document.