PScript
Portable Script Host for Windows
BVO Computing Services Copyright © 2011 Robert D. Riemersma, Jr
Version 1.x August 2011
- Legal
- Introduction
- About PScript
- Deploying PScript
- PScript Command Line Usage
- Using PScript with Launchers
- PScript members Exposed to the Script
- AppDataLocal Property
- Arguments Property
- ArgumentsLine Property
- CD Property
- CopyDir Method
- CopyFile Method
- Del Method
- Environment Method
- Exists Method
- ExpandEnvironmentStrings Method
- MkDir Method
- Quit Method
- Rename Method
- RmDir Method
- RndSubDirOf Method
- Run Method
- ScriptFullName Property
- ScriptPath Property
- Sleep Method
Legal
This document as well as the program PScript itself are copyrighted by the author. Permission is granted to anyone to reproduce, distribute, or use these items as long as the Copyright notice is not removed. Permission is further granted to anyone to create derivative works as long as the original author is credited.
No warranty of fitness and safety, or offer of support should be inferred. This is "as is" software to be used at your own risk.
Windows, Internet Explorer, VBScript, and JScript are Trademarks of Microsoft Corporation.
Introduction
PScript was developed for use in running "portable" software in conjunction with a launcher utility such as my own PockeTop Portable Desktop. Such software is typically carried from computer to computer on a removeable medium such as a CD-ROM, USB drive, or floppy disk.
Normally for software to run "portably" it should be written and packaged such that it does not need to modify system state on the host computer in order to run. For example such programs should not require COM registration or otherwise alter the system registry.
Often however it can be useful to perform pre- or post-processing around a program run. For example the program and its data might be stored on a USB flash memory drive but you may wish to minimize wear on the device. You could copy work files to the host hard drive before running against them, then optionally copy the altered work files back to the flash drive after ending the program, and finally clean up the host hard drive by deleting the work files.
Using .CMD or .BAT files for this purpose works, but can be clunky leaving console windows open on the desktop. Windows Script could be an answer, but sadly in many portable software usage scenarios such as libraries, cybercafes, and corporate settings Windows Script Host (WSH) is disabled or locked down for system safety reasons.
About PScript
PScript is a portable script host you can use instead of WSH's CScript and WScript hosts.
It adds a few useful properties and methods to the bare bones of the VBScript and JScript engines already present on the host machine. However PScript does not use any tricks to provide any system access the running user would not already have, and doesn't even offer HKCU registry manipulation.
It should run just fine even when "scripting has been locked down" on the host, as long as the Microsoft script engines are available. They normally would be in order for Internet Explorer pages to host script.
PScript should provide enough tools to suit its intended purposes without even using the WShell and FileSystemObject objects, which are also sometimes locked down along with 'CScript.exe' and 'WScript.exe'.
Deploying PScript
Copy 'PScript.exe' anywhere you want on your portable disk medium. Perhaps a directory named 'PScript'.
Also copy the sub-directory 'PScriptBin' and its contents inside that directory.
You're done.
The program contains an embedded isolation and trustinfo manifest that lets it use 'msscript.ocx' without registering it on host computer(s).
PScript Command Line Usage
Usage
Entering PScript /?
gets you:
The [arguments...]
values are passed to the script.
The script will run silently unless functions such as MsgBox()
or InputBox()
are used, or if the script engine detects a script timeout -- which raises a continue/quit dialog.
Normally the default timeout (never) is fine, but when debugging a script containing loops you might want to set a small value like 5 or 10 seconds.
Exit Codes
[result] | Values: |
---|---|
No Errors | 0 |
Command Syntax Error | 1 |
Bad Script File Extension | 2 |
Script File Not Found | 3 |
Script Syntax or Run Time Error | 4 |
A script syntax error or run time error will also raise a dialog describing the error and where it occurred.
Script File Name Extensions Accepted
[.] | [=] |
---|---|
.VBS, .VBE | VBScript engine will be invoked |
.JS, .JSE | JScript engine will be invoked |
Using PScript with Launchers
Typically you would have your launch utility run PScript passing it the name of an application wrapper script.
This script would consist of a few lines of VBScript or JScript to perform setup and teardown actions, wrapping a Run
of the application itself.
Sample Script:
Script Assumes the Folder Structure:
[lv1] | [lv2] | [lv3] |
---|---|---|
'SomeDir' (the application directory on the removable medium) | ||
'MyApp.exe' | ||
'MyAppWrapper.vbs' | ||
Volatile (a "work data" directory, database, documents, etc.) | ||
'MyApp.mdb' | ||
'SomeDoc.rtf' | ||
etc. |
PScript members Exposed to the Script
The PScript host exposes a number of properties and methods to your scripts as global members.
This means you can use them directly instead of using the PScript object to qualify them:
AppDataLocal Property
Read Only, String
- Returns the path to the host machine's local appdata folder for the logged on user.
Useful as a place to use for work data. There is no trailing "\" character returned.
Arguments Property
Read Only, 1-based Collection
- Contains the contents of the command line
[arguments...]
string, parsed by blank space delimiters into individual de-quoted items.
Quotes must be used around items with spaces inside them. - The items are in their original sequence and do not include the '
//T:nn
' switch value when used to run PScript. - Access is by index value from
1
to.Count
as in:
These values are most useful when the script will use the arguments itself.
ArgumentsLine Property
Read Only, String
- Contains the original text of the PScript command line following the script file name or '
//T:nn
' switch (if any).
Most useful when the entire set of[arguments...]
will be passed to the wrapped application.
Any quotes in the original command line are preserved intact.
CD Property
Read/Write, String
- This property may be used to read or set the current directory of the running script and is inherited by application runs the script wraps.
- Reading
CD
returns the current directory setting for the current drive. - Setting
CD
also changes the current drive to the drive (if any) in the new value.
CopyDir Method
Arguments:
Source
As String
Dest
As String
Returns:
*no return value*
- This method copies the
Source
directory which must exist and recursively copies any files and sub-directories it contains to theDest
directory, which must not previously exist.
CopyFile Method
Arguments:
Source
As String
Dest
As String
Returns:
*no return value*
- This method copies the
Source
file as theDest
file.
Drive and directory paths may be included.
Del Method
Arguments:
File
As String
Returns:
*no return value*
- This method deletes the file File, which must exist.
Drive and directory path may be included.
Wildcards * and ? are allowed.
Environment Method
Arguments:
Variable
As Variant
Returns:
String value
- This method accepts an environment
Variable
name (String) or number (Integer, Long, etc.) and returns the corresponding value. - A number is truncated to a whole number value and will return the value of the corresponding environment variable (starting at 1).
If the number is beyond the end of the environment variables list an empty String ("") is returned. - This is most useful for enumerating all of the environment variable values, which is itself is not very useful in scripts.
Exists Method
Arguments:
File
orDir
Returns:
Boolean value
- This method can be called to determine whether the
File
orDir
exists.
Drive and directory path may be included.
ExpandEnvironmentStrings Method
Arguments:
EnvString
As String
Returns:
String value
- This method accepts a text string, usually a path with environment strings within
%%s
, and returns the expanded value.
Example:
"%WINDIR%\MyFile.txt"
returns "C:\Windows\MyFile.txt"
MkDir Method
Arguments:
Path
As String
Returns:
*no return value*
- Creates the directory
Path
.
Drive and directory path may be included.
Directory must not already exist.
Quit Method
Arguments:
*none*
Returns:
*no return value*
Rename Method
Arguments:
OldPath
As String
NewPath
As String
Returns:
*no return value*
- This method renames a file or a directory.
It can move a file between drives but not a directory.
Rename will not create a new file or directory.
Drive and directory paths may be included.
Wildcards are not allowed.
RmDir Method
Arguments:
Path
As String
Deep
As Boolean (optional, default False)
Returns:
*no return value*
- This method removes a directory, or can optionally do a "deep" remove that recursively deletes all sub-directories and files before deleting the specified directory itself.
Wildcards are not allowed.
RndSubDirOf Method
Arguments:
Path
As String
Returns:
String value
- This method accepts a directory
Path
and generates a unique sub-directory name within that directory, returning the final sub-directory path.
The value is tested to make sure it does not already exist before returning, if so another is generated and test until a new one has been created. - The result value will be a relative (to the current directory and drive) path if a relative path was provided and an absolute (full) path if that was what was provided.
Examples:
"SomeDir"
returns "SomeDir\X81A34CF0"
"F:\Data"
returns "F:\Data\X19B3E27"
Run Method
Arguments:
Program
As String
ProgArgs
As String (optional, default "")
WindowStyle
As VbAppWinStyle (optional, default vbNormalFocus)
WaitOnReturn
As Boolean (optional, default False)
Returns:
Long value
- This method can run an external program such as your wrapped application.
TheProgram
name is the file name of the EXE to run.
It can be a relative or absolute file path and must not have quotes since PScript will quote it for you.
ProgArgs
is the arguments string to be passed on the command line. - The default value for
WindowStyle
is normally the correct choice.
Possible values include:
[option] | [value] |
---|---|
vbHide | 0 |
vbNormalFocus | 1 |
vbMinimizedFocus | 2 |
vbMaximizedFocus | 3 |
vbNormalNoFocus | 4 |
vbMinimizedNoFocus | 6 |
WaitOnReturn
determines whether the script continues to run past theRun
call or waits until the external program completes.
Typically you want to specify True for this argument.
Examples:
Run "G:\My App\MyApp.exe", "/K /I:""more power"" /T", , True
Const vbMinimizedNoFocus = 6
Run "prog", "/Q", vbMinimizedNoFocus
Run "prog", , , True
- The return value is the return code from the program.
ScriptFullName Property
Read Only, String
- Returns the full path and name of the running script.
ScriptPath Property
Read only, String
- Returns the full path of the running script not including the file name.
There is no trailing "\" character returned.
Sleep Method
Arguments:
Milliseconds
As Long
Returns:
*no return value*
- Simply puts the script "to sleep" for the requested number of milliseconds.
The actual sleep interval will be at least that long, possibly somewhat longer.