|
The Micro Script Host application is based on the script
hosting features supplied by newObjects
ActiveX Pack1 and is distributed with it. In most cases the
developers use the ActiveX Pack1 library with other script hosting
environments (such as ASP/ALP, WSH and so on) or embed it in their
applications to provide additional features (including custom script
hosting). However very often one needs even a simple hosting application
at hand which can be used to write a few lines and run them.
Unfortunately there is no such host provided by Microsoft for all their
platforms (desktop and Windows CE) at the same time. This was the reason
to include this helper application in the ActiveX Pack1 distribution
packages.
The host is quite simple, but it is powerful enough to allow
developers, power users or skilled administrators write scripts and run
them right on their machine or device. Together with the ActiveX Pack1
library you have a huge set of components that allows you to perform
wide variety of tasks without need to search for additional components.
Requirements
Usage
The elements of the
user interface
Command line
Scripting
API (members reference)
Script execution process
The Micro Script Host is currently available for Windows
95/98/ME/NT/2k/XP/2k3 and later versions of the server/desktop Windows
versions. It is also available for Windows CE 3.0 and later. Separate
version is available for Pocket PC (2000,2002,Windows Mobile 2003 and
later). Versions are available for earlier Windows CE (2.11) versions
but they are no longer supported and they may be not fully functional.
The newObjects ActiveX Pack1 must be installed on the machine in
order host to run.
Also you need at least one Active Script language engine on the
machine/device (on desktop Windows-es this you have almost always
VBScript and JScript. However on Windows CE (including Pocket PC) not
all the script languages are installed by default (depends on the
specific edition of your device). Redistributtable packages are
available from the vendors or from Microsoft. On Windows CE 3.0 and
later you can almost always count on the JScript existence (does not
exist only on some specific devices designed for specific purposes
only), VBScript, if not present (many Windows Mobile 2003 devices does
not have it pre-installed), may be installed from the Windows Mobile web
site (install the VB runtimes - on CE VB uses VBScript to execute the VB
applications).
When installed a shortcut is created in the start menu (Programs/newObjects/ActiveX
Pack1) or in the Programs (on Windows CE devices). The exe name is
nwmicrohost.exe. It is installed in the Windows directory in order to be
easily accessible from the command line. So you can type on the command
line (or create such shortcuts or use bat/cmd files) just
nwmicrohost.exe. See the Command line section below for the supported
parameters and passing parameters to the script.
Except from the command line you can specify a script file to be
executed from the Run menu item. By default (if not prevented
using the command line option -nohelp) a brief help information
is displayed in the output window.
The elements of the user
interface:
There are 3 elements (illustrated on the images below):
Output area (always visible) The output of the script is
displayed in it.
Input area (visible only if input is requested). A place
where the user is asked by the script to enter text needed by the
script to continue its execution.
Submit button (visible only if input is requested). A button
the user clicks to submit the text entered into the input area.
The both elements are always visible or invisible together.
| Micro
Script Host on desktop Windows OS (9X/ME/NT/2k/XP/2k3 etc.) |
 |
 |
| Micro
Script Host on Pocket PC |
 |
 |
Aside of that the script may invoke message box - informative (with
only OK button) and yes/no questions (with yes and no buttons).
The general syntax of the command line used to invoke the Micro
Script Host is:
microhost.exe [-nohelp] [scriptfile | -END] [script parameters]
All the parameters before the script file (which will be executed)
or -END parameter are host parameters they are accessible to
the script through the SysParameter method (see below). These
parameters are checked by the host you must not specify nothing which
is not supported by the current version. Currently only the -nohelp
parameter is supported which prevents the host from displaying the
help and about information in the output area when the host is
started.
All the parameters after the script name or -END parameter are not
checked by the host and are accesible to the running script trough the
Parameter method (see below).
The -END parameter. It is possible to execute the Micro
Script Host without script file specified. However you may want to
execute later several scripts manually (from the Run menu), but
still want to pass parameters to them. In this case you can specify
-END instead of script file name and all the scripts you start then
manually will be able to reach them through the Parameter
method.
The script currently running into the host may refer to the namespace
Host. This namespace exposes the methods implemented by the Micro
Script Host application. To refer a method in your script you write for
example:
Host.WriteLine "Hello World!"
or
Set o = Host.CreateObject("mycompany.myprogID")
If you have experience with Windows Scripting Host you can think for
the Host namespace as for an equivalent to the WScript
namespace in WSH.
The list of the supported members is:
 |
Msg(text) |
Shows a message box with only OK
button. Useful for displaying of short notification messages that
should attract the user.
Parameters:
text - A string. The text to be displayed in the
message box.
Sample:
VBScript: Host.Msg "The file " & myfile & " not found"
JScript: Host.Msg("The file " + myfile + " not found");
|
|
Write(text) |
Writes text to the output area (see
above). New line is not placed after the output.
Paramters:
text - The text to be written into the output.
Sample:
VBScript: Host.Write "Hello World!"
JScript: Host.Write("Hello World");
|
|
WriteLine(text) |
Writes text to the output area (see
above). New line is placed after the output.
Paramters:
text - The text to be written into the output.
Sample:
VBScript: Host.WriteLine "Hello World!"
JScript: Host.WriteLine("Hello World");
|
|
Ask(text) |
Displays message box with yes and no
buttons. Returns True if the Yes button has been clicked and False
if the user clicked the No button.
Parameters:
text - The text for the message box
Sample:
VBScript: If Host.Ask("Do more?") Then ...
JScript: if (Host.Ask("Do more?") { ...
|
|
RequestInput(button_text) |
Requests user input. The request
appears after the execution of the script's global part completes.
I.e. you can call this method and do more work after it. The
actual input is passed to the script using the OnInput
event (a routine that the script must implement). See also the
script execution process after this section.
Parameters:
button_text - the text which will be displayed on the submit
button (see the UI elements above).
Sample:
VBScript: RequestInput "Directory to list"
JScript: RequestInput("Directory to list");
|
|
Parameter(n) |
Returns the n-th script parameter from
the command line. See also the Command line syntax above. You
should check the ParameterCount before requesting the parameter -
if the parameter count is less then the index specified an error
will be shown.
Parameters:
n - the index (positive integer) of the parameter in
the script parameters set.
Sample:
x = Host.Parameter(3)
|
|
SysParameter(n) |
Returns the n-th host parameter from
the command line. See also the Command line syntax above. You
should check the ParameterCount before requesting the parameter -
if the parameter count is less then the index specified an error
will be shown.
Parameters:
n - the index (positive integer) of the parameter in
the host parameters set.
Sample:
x = Host.SysParameter(3)
|
|
ParameterCount(bHost) |
Returns the number of the command line
parameters. If bHost is True returns the number of the host's
parameters, if the bHost is False returns the number of the
script's parameters. See also the Command line syntax above.
Parameters:
bHost - Boolean parameter which tells the host which
count to return (see above description).
Sample:
c = Host.ParameterCount(true)
|
|
Exit() |
Exists the script host (closes the
application). Should be used mostly in scripts designed to be
executed with command line activation which are expected to exit
after finishing their work. There is no need to call this method
in order to complete the script - it is just a way to close the
application if needed. |
|
Clear() |
Clears the output area (removes all
the text from it). |
|
CreateObject(id_or_clsid) |
Creates and returns the specified COM
object. It is strongly recommended to use this method instead of
any internal script obejct creation facilities (such as
CreateObject in VBScript and new ActiveXObject in JScript).
Parameters:
id_or_clsid - A string that specifies either the
progID or the class ID (in {....} form) of the object to be
created.
Sample:
VBScript: Set o = Host.CreateObject("ADODB.Connection")
JScript: o = Host..CreateObject("ADODB.Connection");
|
|
SetInput(text) |
Sets the current contents of the input
area. Used to set default value for the user input. May be called
even if the input window is currently not shown - next time it
shows it will display this text.
Parameters:
text - A string specifying the text to set in the
area.
Sample:
VBScript: Host.SetInput "\MyDocuments\MyFolder"
JScript: Host.SetInput("\MyDocuments\MyFolder");
|
|
RuntimeParameter(name) |
Fetches a run-time parameter supported
by the host. The runtime parameters are used to allow the script
learn some information that will help it reach the resources it
needs.
Parameters:
name - The name of the parameter. The currently
supported names are:
ScriptFile - The full path name of the script file name
currently executed (self name)
ScriptPath - The full path name of the directory
containing the script which runs in the host.
Sample:
VBScript: myfile = Host.RuntimeParameter("ScriptPath") & "myfile.txt"
JScript: myfile = Host.RuntimeParameter("ScriptPath") + "myfile.txt";
The above sample constructs the full path name of a text file
which is in the same directory where the currently running
script resides.
|
 |
OnInput(text) |
This function must be implemented in
the script if it needs to receive input from the user. Calls to it
can be received ONLY after the initialization of the script
completes. I.e. all the global script is completed (the script
code outside any function/sub). Therefore the script that requires
input must be designed to use this function as invocator for the
tasks that depend on the user input.
Parameter:
text - The user input
See the sample in the following section |
There are generally two types of scripts for Micro Script Host:
Scripts that do not require textual user input and scripts that require
it.
The scripts that do not require input are simply executed linearly -
from the beginning to the end. If any functions are implemented it is up
to you to call them from certain points in the global part of the script
code (the code outside any function/sub).
The scripts that require also user input must implement OnInput
routine and they must be designed to do whatever work depends on the
user input from it. So, you cannot require the user to enter additional
parameter(s) during the linear part of the execution of the global code.
The user is allowed to enter parameter(s) only after this part
completes. Thus the execution process does not complete with the end of
the script. If the RequestInput has been called before that point
the script remains in memory and the host displays the input area
and the submit button. When the user clicks the submit button the
implemented by the script OnInput function/sub is called with
parameter containing the user input. The sample below illustrates the a
simple script that requires input.
VBscript:
Host.Clear
Dim sf
set sf = Host.CreateObject("newObjects.utilctls.sfMain")
Sub DoDir(s)
set d= Sf.OpenDirectory(s)
set c = d.contents
for each I in c
Host.WriteLine i.name & vbtab & i.type & vbtab & i.size
next
End Sub
Sub OnInput(s)
DoDir s
If Host.Ask("List another directory?") Then
Host.Clear
Host.RequestInput "Enter directory"
Else
Host.Exit
End If
End Sub
OnInput "\"
JScript:
Host.Clear();
Host.WriteLine("JScript micro host sample");
// Enum command line parameters
Host.WriteLine("Param count: " + Host.ParameterCount(false));
for (i = 1; i <= Host.ParameterCount(false);i++) {
Host.WriteLine("Param" + i + "=" + Host.Parameter(i));
}
Host.WriteLine("Sys Param count: " + Host.ParameterCount(true));
for (i = 1; i <= Host.ParameterCount(true);i++) {
Host.WriteLine("SysParam" + i + "=" + Host.SysParameter(i));
}
Host.WriteLine("Asking for input");
Host.RequestInput("Enter something");
function OnInput(s) {
Host.WriteLine("You entered: " + s);
Host.Msg("And now exiting ... click ok");
if (s == "exit") Host.Exit();
}
In more complex scripts the OnInput routine may include switch/Select
Case statement(s) that will route the execution depending on the
user's input. Of course, you can implement the actual work in other
routines and call them from the OnInput method with whatever
parameters they require.
The script execution finishes when the user requests no further user
input and also there is no more code to execute (e.g. the OnInput
function/sub exits and no RequestInput has been called before
that point.
|
