shell_command

Synopsis

                        module _shell_command {
string+read+req _command;
int+read _active;
int+read _on_inst;
char+write _stdout[];
<user parameters>};

Description

shell_command executes a specified command string and places any data output by that string into the stdout array. The command string is executed synchronously: while the command is running, the module is running.

The command string can take additional user-defined parameters. Because the update method for the shell_command module has the no_meth_ctx property set to 1, these parameters can cause the update method to execute when they change. When the command string is processed, the string values of these parameters are substituted into the command string.

On Windows, the command string is assumed to be the name of executable program along with arguments to the program. To obtain behaviour similar to typing a command to a command shell, prepend "cmd /C" to the command. Don't forget the "/C" or AVS/Express will freeze.

For example: "cmd /C dir"

Input

command

The command parameter specifies a string that contains the command as it is delivered to the shell on your system. This shell command can contain variables delimited by the at (@) character. The names of the variables are resolved to be names of parameters that you have added to the module. For example, you might define the shell_command module in V like:

#ifdef MSDOS

GMOD.shell_command ls_command {

string my_dir = "c:\\temp\\";

command = "cmd /C dir @my_dir";

};

#else

GMOD.shell_command ls_command {

string my_dir = "/tmp/";

command = "ls @my_dir";

};

#endif

In this example, as the my_dir parameter's value changes, the update method runs and the command is executed. You can set the nonotify attribute on a parameter that you add to prevent it from causing the method to run.

active

When set to 0, this parameter disables the execution of the command. You can use this to prevent the command from being executed as the command or other parameters are being changed.

on_inst

When set to 0, this parameter prevents the execution of the shell command in response to the instance event.

Parameters

none.

Output Port

stdout

This is a binary array of characters that are derived from the standard output stream of the executed command.

par relative

This parameter is a pointer to an object that is the context in which the V commands are executed. If its value is left unset, the Applications object is used. The value of this parameter is the parent for objects created in the V statements. It also is the starting point to start searching for object names referenced by the V statements.

no_errors

If this parameter is non-zero, any errors generated by the V commands to be executed are ignored.

sync

If this parameter is non-zero, all methods triggered by parameters modified by the V commands are run before this module completes execution.

mode

If mode is set to 0, then the entire string in parse_v is executed within a single push-pop context, i.e.:

push
parse_v statements
pop

However, if mode is not equal to zero, then each statement is executed in it's own push-pop context. E.g. for the statement " int v=1; v=v+1; ... ":

push
int v=1;
pop
push
v=v+1;
pop .

and so on.

Example

This is an example of how to use the parse_v object to attach a button to the visibility of a UIshell object. The parse_v module fires when the button is pressed. Its command string sets the visibility parameter of the UIshell to 0. Since the relative parameter is connected to the UIshell object, the V statement "visible = 0;" sets the value of the parameter UIshell.visible.

GMOD.parse_v parse_v {
v_commands = "visible = 0;";
trigger => <-.UIbutton.do;
relative => <-.UIshell;
};
UIshell UIshell;
UIbutton UIbutton {
parent => <-.UIshell;
};