PScript

Portable Script Host for Windows

BVO Computing Services Copyright © 2011 Robert D. Riemersma, Jr

Version 1.x August 2011

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:

1
2
3
4
5
6
7
8
9
BVO Computing Services
PScript Portable Script Host Version 1.0

Usage: PScript scriptname.extension [options...] [arguments...]

Options:
//T:nn Timeout in seconds: Maximum time script is permitted
   to run.  The value 0 means "system detects hang" and
   -1 (default) means "never time out."

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:
'MyAppWrapper.vbs'

Const vbNormalFocus = 1
Dim WorkDir

WorkDir = RndSubdirOf(AppDataLocal)
CopyDir ScriptPath & "\Volatile", WorkDir
CD = WorkDir
Run ScriptPath & "\MyApp.exe", ArgumentsLine, vbNormalFocus, True
CopyDir WorkDir, ScriptPath & "\Volatile"
RmDir WorkDir, True 'Deep remove!
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:
    Dim I, Args
    
    Args = ""
    For I = 1 To Arguments.Count
        Args = Args & ", " & Arguments(I)
    Next
    Or:
    Dim I, Args
    
    Args = ""
    For I = 1 To Arguments.Count
        Args = Args & ", " & Arguments.Item(I)
    Next
    

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 the Dest 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 the Dest 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 or Dir

Returns:

Boolean value

  • This method can be called to determine whether theFile or Dir 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.
    The Program 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 the Run 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.
Edit
Pub: 01 Feb 2021 19:23 UTC
Views: 606