Programmer Guide/Command Reference/MACROX: Difference between revisions

From STX Wiki
Jump to navigationJump to search
(Created page with '{{DISPLAYTITLE:{{SUBPAGENAME}}}} MACROX <var>macroname macroarguments</var> The <code>MACROX</code> command executes the macro <var>macroname</var> ''in the current variable en…')
 
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 2: Line 2:
  MACROX <var>macroname macroarguments</var>
  MACROX <var>macroname macroarguments</var>


The <code>MACROX</code> command executes the macro <var>macroname</var> ''in the current variable environment'', passing it the arguments specified by <var>macroarguments</var>. Any changes the macro does to the environment will persist after its execution. This includes any unwanted changes, so be careful.
The <code>MACROX</code> command executes the macro <var>macroname</var> ''in the current variable environment'', passing it the arguments specified by <var>macroarguments</var>. Any changes the macro does to the environment will persist after its execution. This includes any unwanted changes, so be careful (for a different behaviour, see below, or directly refer to the {{STX}} statements <code>[[Programmer_Guide/Command_Reference/MACRO|MACRO]]</code>, and <code>[[Programmer_Guide/Command_Reference/SHELL|SHELL]]</code>).


The macro source code <var>macroname</var> must be loaded (see <code>[[User Guide/Workspace/Pre-configured profiles|LOAD]]</code>)The <var>macroarguments</var> passed to the macro are stored in the variable <code>#ARGV</code> of the called macro. Because of the special command-line processing in {{STX}}, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from <var>macroarguments</var> before it is assigned to <code>#ARGV</code>.
The macro source code <var>macroname</var> must be loaded (see the <code>[[User Guide/Workspace/Pre-configured profiles|LOAD]]</code> command). The <var>macroarguments</var> passed to the macro are stored in the variable <code>#ARGV</code> of the called macro. Because of the special command-line processing in {{STX}}, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from <var>macroarguments</var> before it is assigned to <code>#ARGV</code>. For more information on argument passing, and parsing, see [[Programmer_Guide/Concepts/Argument_Passing|Argument Passing]]. For a broader information on macro programming, see [[XXX|Script Programming in {{STX}}]] or [[Programmer_Guide/STx_Guru|Becoming an S_TOOLS-STx Guru (in 240.918 simple steps)]].


For information about macro definitions (header) and argument parsing see the [[XXX|Script Programming in {{STX}}]]. Many macros use the call-format: name command arguments (e.g. <code>MSGBOX MSG text</code>). If you want to pass quoted arguments to such a macro, use the format <code>MSGBOX 'MSG text'</code> instead of <code>MSGBOX MSG 'text'</code>. This is necessary because the argument string <code>MSG 'text'</code> is passed (after command-line processing) as <code>MSGtext</code> to the macro.If a new shell is called to run a macro, the id (8 hex digits) is assigned to the variable <code>#SHELL</code> of the caller. In the new shell, the variable <code>SHELL</code> is set to '<code>this_shellid caller_shellid</code>'. The two variables can be used to identify the shells in communication messages.It is not necessary to use the command <code>MACRO</code> explicitly, because the interpreter tries to execute all 'non-shell' commands as a macro. This means the command line <code>MACRO macroname</code> is equivalent to command line <code>macroname</code>.
Note again that the <code>MACROX</code> command executes your subroutine in the very execution environment of the caller, meaning that any side-effects your subroutine may have to your local variables will persist. This is often dangerous, and not normally considered a healthy style of programming, but, obviously, there are cases where it is what you want.
 
Nevertheless, normally you will prefer having your subroutine executed in a separate execution environment. This is done with the {{STX}} command <code>[[Programmer_Guide/Command_Reference/MACRO|MACRO]]</code> (note the missing character "X"). If you want to separate the subroutine even more thoroughly from your current environment, you may even have it executed by a separate instance of the {{STX}} shell (i.e. the {{STX}} command interpreter), by using the <code>[[Programmer_Guide/Command_Reference/SHELL|SHELL]]</code> command for executing the subroutine. In this case, your subroutine will find start its existence in a clean environment, without local variables being inherited from the caller.

Latest revision as of 16:59, 25 April 2014

MACROX macroname macroarguments

The MACROX command executes the macro macroname in the current variable environment, passing it the arguments specified by macroarguments. Any changes the macro does to the environment will persist after its execution. This includes any unwanted changes, so be careful (for a different behaviour, see below, or directly refer to the STx statements MACRO, and SHELL).

The macro source code macroname must be loaded (see the LOAD command). The macroarguments passed to the macro are stored in the variable #ARGV of the called macro. Because of the special command-line processing in STx, all string replacements are applied to and all special parsing information (e.g. quotation marks) are removed from macroarguments before it is assigned to #ARGV. For more information on argument passing, and parsing, see Argument Passing. For a broader information on macro programming, see Script Programming in STx or Becoming an S_TOOLS-STx Guru (in 240.918 simple steps).

Note again that the MACROX command executes your subroutine in the very execution environment of the caller, meaning that any side-effects your subroutine may have to your local variables will persist. This is often dangerous, and not normally considered a healthy style of programming, but, obviously, there are cases where it is what you want.

Nevertheless, normally you will prefer having your subroutine executed in a separate execution environment. This is done with the STx command MACRO (note the missing character "X"). If you want to separate the subroutine even more thoroughly from your current environment, you may even have it executed by a separate instance of the STx shell (i.e. the STx command interpreter), by using the SHELL command for executing the subroutine. In this case, your subroutine will find start its existence in a clean environment, without local variables being inherited from the caller.

Navigation menu

Personal tools