Scripting Guide - Useful Tools and Information

• Language Engines
• Script Hosts ("runners")
• Documentation
• Editors
• Debugging
• Links to Sites with Scripting and ASP Information

The Challenge - Learning VBScript or JScript is relatively easy. The main challenge in learning how to write scripts is learning about all of the objects at your disposal. There are probably more than a hundred really useful objects if you include ACP's, MaxIm DL's, the ASCOM Telescope and Focuser, NOVAS, Kepler, the XML/RTML engine, the PinPoint Astrometric Engine, and the standard Windows objects for manipulating files & folders, the ActiveX Database Objects (ADO, the standard way to program databases on Windows, and of course the Active Server Pages suite of objects.

On 64-bit systems you need to be doing all of this in the 32-bit environment. That means using the 32-bit flavor of CMD shell, debugggers, and minding the paths to programs (the "(x86)" area of Program Files. If you're reading this page, you are a programmer... this shouldn't be too difficult to deal with.

There are many techniques and tools that you can learn only by reading code. All of ACP's scripts and Active Server Pages are heavily commented so you can learn. Look at the code, read about the objects used, write a few "playtime" scripts to use the objects, and you will soon start to feel comfortable. Don't be intimidated!

Language Engines

Most people are surprised to discover that the common scripting language engines are already resident on their Windows computers. If you have a very old version of Windows, the ASCOM Platform installer updates your old system to include the latest VBScript and JScript engines, Version 5.7. These engines are used in several applications within the Windows operating system, as well as internally by ACP. More on that in the next section.

Script Hosts ("runners")

The language engines cannot be used by themselves. In order to run a script, an engine must be attached to a script host, which provides the environment for loading the script text into the engine and executing the language in the script. In the Windows Operating System, there are three script hosts:

• The Windows Scripting Host is the standard script runner on Windows. It is accessible from a command (CMD) shell via the cscript command, and via double-clicking a script file (which invokes the wscript host). See Running Scripts from Windows. This facility is widely used for Windows administrative tasks and automation of processes. On a 64-bit system you must be running the 32-bit cscript and the easiest way is to start a 32-bit CMD shell from C:\Windows\SysWow64\cmd.exe. Put a shortcut on your desktop and you can adjust the size and colors of the shell window in the shortcut, giving you a convenient way to get into this shell.
• Microsoft Internet Explorer (all versions) has its own script host. It is used to execute client-side scripts embedded within web pages by the web page author. These scripts are either contained within <script> tags, or within Dynamic HTML snippets. Usage of scripts within web pages is very common. On a 64-bit system you must be running the 32-bit Internet Explorer.
• Microsoft Internet Information Server has its own script host as well. Version 5 and before uses Windows Script for Active Server Pages. As an ACP user, you will not be using IIS!

ACP is unique among astronomy automation packages in that it has two of its own script hosts.

The preferred runner for ACP scripts is the ACP scripting console. It provides you with an environment for astronomy related work, and can be controlled through the web server. It can also be set to log output to a file, making it easy to keep journals of script execution. Scripts run within ACP's console have automatic access to the Telescope, Camera, Dome, Weather, Utility, Prefs and other ACP objects built in.

In addition, ACP has its own built-in implementation of so-called "classic" Active Server Pages for dynamic web content. ACP's built-in web server included a script host and a set of objects that implement the Microsoft Active Server Pages environment. Web pages that are served by ACP undergo an interpretation by the ASP engine whereby the ASP (mixed HTML and script) are translated into scripts and executed. The output of the ASP page is converted to HTML and sent to the browser. Again, ACP's ASP environment includes automatic access to the Telescope, Camera, Dome, Weather, Utility, Prefs and other ACP objects.

Documentation

Within ACP's Help is the complete Microsoft Windows 5.6 documentation package. This has detailed language reference info for VBScript and JScript (Microsoft's extended JavaScript which comes with Windows) and reference information for Scripting Runtime, which has some very useful built-in objects. Read about the FileSystemObject and RegExp objects (the latter are different in VBScript and JScript) as well as the languages.

For MaxIm DL, and ASCOM objects (NOVAS, Kepler, etc.) consult the supplied documentation. ACP includes documentation of all of its objects as well as its Active Server Pages object suite.

Editors

At first, it seems like using Notepad for writing scripts is so easy. But eventually, you're going to look for alternatives. Leading the way for a new generation of scripting editors is PrimalScript from Sapien Technologies . This editor is language sensitive with syntax coloring for many languages including VBScript, JScript, Perl, and Python. It has (limited) "intellisense", popup tips for syntax and object interfaces. You can run scripts from within PrimalScript and see the results in an output window. There are other programmer's editors out there, however most do not support the newer scripting languages with language sensitivity and syntax coloring.

Syntax Checking

If you write in JScript, there is a tool that will save you from countless hours of time and loads of pain: JavaScript Lint. This tool can be integrated into PrimalScript so that one click produces a deep-check of your script for all sorts of errors. You can click on the error message and be taken to the offending line in your script. In VBScript, be certain to include the Option Explicit statement at the beginning of all of your scripts. There's nothing more difficult than troubleshooting a bug caused by a misspelled variable receiving an important value assignment! Without Option Explicit, VBScript happily defines the new/wrong variable and the fun starts.

Debugging

ACP normally does not start a script debugger when there is an error in a script or ASP page. Instead, it traps the error and prints an error message and traceback to the ACP console. To enable debugging within ACP, turn on the "Enter debugger on script errors" switch on the Debugging tab of ACP's Preferences dialog. Before doing this, however, you must have installed and configured a script-capable debugger.

An excellent tool for debugging ACP scripts is the the debugger included with Microsoft Visual Studio (2005-2010 complete/pro) and Visual Studio 2015 Community Edition (recommended) for debugging scripts. If you have Visual Studio, click here for details on configuring the Visual Studio debugger for scripts. Note that Visual Studio 2015 Community Edition (recommended) is free from Microsoft (a huge corporate change with great benefit).

If you don't want to install the (huge) Visual Studio, there is still hope! We have included the very basic Microsoft Script Debugger 1.0 with ACP. You can find the installer for it under Program Files, ACP, in the Misc subdirectory. This is a really basic debugger but it will serve you well for light debugging needs.

There are a few tricks that will save you a load of headaches when debugging with either tool:

• To enable the debugger in ACP, turn on the Enter Debugger on Errors option on the Debugging tab of Preferences.
• To put a breakpoint into your source code, use a Stop statement in VBScript, and a debugger; statement in JScript.
• To inspect a variable in VBScript, type "? variable" in the debugger command window. For JScript, just type the variable name in the command window (no '?').
• You can call a function from the debugger's command window. Any valid expression in the script's language may be entered into the command window. This is really useful!
• If you change a script, you must start it from scratch. You cannot change a script while it is executing.
• When using the Windows Scripting Host (cscript/wscript) instead of ACP's console, the debugger will trap errors in your script only if you type //D on the cscript command line when running the script. Yes there are two slashes on that option (and other Windows Script Host options).
• When using the Windows Scripting Host, to start your script in the debugger, add the //X option.

Links to Sites with Scripting

Here are some hand-picked sites that offer lots of useful info on Windows Scripting in general.

• Microsoft Windows Scripting
• Rob van der Woude's Scripting Pages
• Active Server Pages Tutorial (W3C Schools) (ASP Reference included with ACP Help)