Programmer Guide/Command Reference/MACRO: Difference between revisions
No edit summary |
No edit summary |
||
| Line 2: | Line 2: | ||
MACRO <var>macroname macroarguments</var> | MACRO <var>macroname macroarguments</var> | ||
The <code>MACRO</code> command executes the macro specified by <var>macroname</var>, passing to it the arguments specified by <var>macroarguments</var>. The macro will be started in its own variable environment | The <code>MACRO</code> command executes the macro specified by <var>macroname</var>, passing to it the arguments specified by <var>macroarguments</var>. The macro will be started in its own variable environment, meaning that any changes the macro does to the environment will be lost after its execution. | ||
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 <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>. | ||
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>. | 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>. | ||
Revision as of 17:22, 5 April 2011
MACRO macroname macroarguments
The MACRO command executes the macro specified by macroname, passing to it the arguments specified by macroarguments. The macro will be started in its own variable environment, meaning that any changes the macro does to the environment will be lost after its execution.
The macro source code macroname must be loaded (see LOAD)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 information about macro definitions (header) and argument parsing see the Script Programming in STx. Many macros use the call-format: name command arguments (e.g. MSGBOX MSG text). If you want to pass quoted arguments to such a macro, use the format MSGBOX 'MSG text' instead of MSGBOX MSG 'text'. This is necessary because the argument string MSG 'text' is passed (after command-line processing) as MSGtext to the macro.If a new shell is called to run a macro, the id (8 hex digits) is assigned to the variable #SHELL of the caller. In the new shell, the variable SHELL is set to 'this_shellid caller_shellid'. The two variables can be used to identify the shells in communication messages.It is not necessary to use the command MACRO explicitly, because the interpreter tries to execute all 'non-shell' commands as a macro. This means the command line MACRO macroname is equivalent to command line macroname.
