windows-xp/Source/XPSP1/NT/sdktools/mtscript/docs/usage.txt

**********************  RunLocalCommand ***********************

RunLocalCommand usage:

If RunLocalCommand is called with fWait=true, the call will not return
until the process has exited.  The return value will be an identifier for
the dead process that can be used in a call to GetProcessOutput() and
GetProcessExitCode().  If the return value is zero,
an error occurred and GetLastRunLocalError() can be called to get the
error code.  OnProcessEvent events will be fired for this process. The
returned process ID is only valid until the next call to RunLocalCommand
on that thread.

If RunLocalCommand is called with fWait=false, the call returns
immediately and the return code is the process identifier. If the ID is 0
an error occurred which can be retrieved by calling
GetLastRunLocalError(). The OnProcessEvent event will be fired to indicate
events regarding the process, such as termination. See below for details.

GetProcessExitCode() can be called for any process which has exited.
Calling GetProcessExitCode() if the process is still running is an error.

GetProcessOutput() can be called for any process which had
fGetOutput=true.  If fWait was true, then GetProcessOutput() will return
all information written to STDOUT and STDERR while the process was
running.  If fWait was false, then if the process has terminated the
return value is the same as if fWait was true.  If the process is still
running, all text sent to STDOUT & STDERR up to the current time will be
returned.

For a process which has connected via the IScriptedProcess interface (an
OnProcessEvent event is fired when this happens) the script can call
SendToProcess() to send information to that process. If the process is not
connected a call to SendToProcess will be ignored and the return value is
zero.

OnProcessEvent events:

When OnProcessEvent is fired, the first parameter (lProcessID) contains
the ProcessID associated with the event, the second parameter (bstrEvent)
is a string identifying the event, and the third parameter (vData) is data
associated with the particular event.

bstrEvent='exited': the process has exited and vData is the process exit
code.

bstrEvent='terminated': The process was terminated as a result of a call
to TerminateProcess(). vData will have no data.

bstrEvent='crash': The process or one of its children had an unhandled
exception and was terminated. vData will have no data. (Win2000 only)

bstrEvent='connected': Fired when the process connects to the script
host through the IScriptedProcess interface.

bstrEvent can also be any value set by the running process through the
IScriptedProcess interface. By connecting to this interface, processes
that are aware of the scripting engine can communicate to the script. In
this case, bstrEvent will be an identifier string given by the process,
and vData will contain a parameter string given by the process. The return
value from the OnProcessEvent function is passed to the calling process.
It must be an integer value.


Implementation Notes:
* Return 1 for the processId if fWait=true.
* Return code and output info must be stored per-thread for PID=1.
* Use Win2K's Job APIs to better manage terminating a process.
* Pass an environment variable with a unique ID when creating a process.
Processes should use this ID when calling IScriptedProcess::SetProcessID.
(On win2K only this can be accomplished using the job APIs)



**********************  Script Engine Interfaces ***********************

The interface used for the global interface of the script engines is
IGlobalMTScript. The script engines should use the PublicData and
PrivateData properties on the global object to store data that must be
shared between script engines. The PublicData property is made visible to
an external COM object which can be created remotely. The intent of this
is for the creation of a UI which can manipulate the scripts. The
PrivateData property is for the storage of other global data which should
not be made visible outside the script engine.


**********************  MTScript Service ***********************

The MTScript service is an EXE which runs as a service.  When running, it
registers the RemoteMTScript class as a remotable COM object.  Any number
of these objects can be created at a time and it allows a remote client
to talk to the MTScript engine.  The script engine runs even if no clients
are connected.

Issues:
* Need a way to reset the script engine
* Need a way to download scripts
* Should support both JScript and VBScript


**********************  UI Operation ***********************

A UI to the MTScript engine is created by creating a web page which
instantiates the RemoteMTScript class.  This gives it access to the
public data published by the script engine, which can be used to display
status information and impact the build.  There is also an Exec method on
the COM object which fires an event on the primary script in the script
engine.  The script engine can then take appropriate action depending on
the command.

The RemoteMTScript class also has an event interface which is used to send
notifications back to the web page.

Issue: How does the returning event interface get hooked up? Can you hook
up to events dynamically on an object created via script code?


**********************  Controlling Remote Machines *******************

A script can control remote machines by instantiating the RemoteMTScript
COM object using the standard script mechanism ("new ActiveXObject(...)"
in JScript). The remote machine becomes a slave to the machine which can
then control it.

Hooking up the events on the RemoteMTScript object is done using the
standard JScript event hooking mechanism. If no such mechanism is
available (is there?) then the IGlobalMTScript interface will provide a
mechanism to register and unregister for events on the object.