Primalscript 2007: TFM (2Nd Edition) P

SAPIEN Technologies presents

PrimalScript® 2007: ™ TFM by Don Jones

This publication is copyrighted ©2007 by SAPIEN Technologies, Inc. All Rights are Reserved. No portion of this publication may be reproduced, in whole or in part, by any means currently known or yet to be discovered, without the express written permission of SAPIEN Technologies, Inc. The information in this publication is for the personal use of the reader, and may not be incorporated into any commercial programs, other books, databases, or any kind of software without the express written permission of SAPIEN Technologies, Inc. The author and publisher of this publication have used their best efforts in preparing it. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. The author and publisher make no warranty of any kind, expressed or implied, with regard to the documentation contained in this publication or with regard to the software programs this publication pertains to.

SAPIEN Technologies, Inc. 3212 Jefferson St #288 Napa, CA 94558 (707) 252-8700 www.sapien.com

Library of Congress Cataloging-in-Publication Data Jones, Don PrimalScript 2007: TFM (2nd Edition) p. cm. – (TFM) Includes index. 0-9776597-3-9 1. Electronic data processing—software 2. SAPIEN PrimalScript 3. Software (Computers) I. Series

Produced in the United States of America 1st Printing, 1st Edition

2 Table of Contents

Introduction ...... 8 PrimalScript Editions ...... 8 What’s New in PrimalScript 2007? ...... 10 Technical Support ...... 11 Stay Up to Date ...... 11

Getting Started ...... 12 Security ...... 12 Firewall Considerations ...... 13 Scanning for Tools ...... 14 Optimizing the User Interface ...... 14 Registering Your Product ...... 15 Removing Your License ...... 16 Troubleshooting and Diagnostics ...... 16 General Command-Line Switches ...... 17

Basic Orientation ...... 18 The File Toolbar ...... 19 The Debugging Toolbar ...... 20 The Edit Toolbar ...... 21 The Find Toolbar ...... 22 The View Toolbar ...... 22 The Script Toolbar ...... 23 The PrimalSense Toolbar ...... 24 The HTML Toolbar ...... 25 The FTP Toolbar ...... 26 The Source Control Toolbar ...... 27 The Build Toolbar ...... 28 The Internet Toolbar ...... 28 The Info Toolbar ...... 29 The XML Toolbar ...... 29 Working with Tabs and Panes ...... 30 Selecting a Layout and Color Scheme ...... 32

Core Editor Features ...... 34 Editing Aids ...... 34 Line and Column Numbering ...... 34 Bookmarks and Jumping ...... 35 3 Character Display ...... 36 Clipboard Integration ...... 37 Code Folding ...... 37 Automatic Regions ...... 37 Temporary Regions ...... 38 Named, Persistent Regions ...... 38 Manipulating Regions ...... 39 Search and Replace ...... 40 Basic Search ...... 40 Basic Search and Replace ...... 41 Regular Expression Searching ...... 41 Searching and Replacing in Files ...... 42 Conversion Features ...... 43 Formatting Features ...... 44 PrimalSense™ ...... 46 Oops Resilience™ ...... 49 Infinite Undo™ ...... 49 Recycle Bin ...... 50 File History ...... 50

Browser Panes ...... 52 The Info Browser ...... 53 The Workspace Browser ...... 53 The Tasklist Browser ...... 53 The Type Library Browser ...... 54 The Resources Browser ...... 56 The Class Browser ...... 56 The File Browser ...... 56 The Tools Browser ...... 57 The Snippets Browser ...... 57 The HTML / XML Navigator Browser ...... 58 The Database Browser...... 58

Project Management ...... 60 Starting a Project ...... 60 Projects and Your Workflow ...... 61 Workspace Management ...... 62 Managing Project Items ...... 63 Projects and Source Control ...... 63 Project Properties ...... 64 Managing Configurations ...... 65 4 Local Mode vs. Master Mode ...... 65 Project Publishing ...... 66 Backing up a Project ...... 67 Running a Project ...... 67 Multi-Target Publishing...... 67

Advanced Features and Customization ...... 70 Customizing PrimalScript Toolbars and Shortcut Keys ...... 70 Customizing Keyboard Shortcuts ...... 71 Customizing Toolbars ...... 71 Customizing the Mouse, Menu, and other Options ...... 71 Customizing PrimalScript Options ...... 71 Comparing Files with PrimalDiff™ ...... 76 Checking Spelling ...... 76 Sending and Receiving Files via FTP ...... 77 Miscellaneous Tools ...... 77

Source Control Integration ...... 78 Setting up SourceSafe-Compatible Source Control ...... 78 Setting up CVS-Compatible Source Control ...... 79 Using Source Control ...... 80 Using CVS with PrimalScript ...... 81 Troubleshooting ...... 82

Universal Help ...... 83 MSDN Library Integration ...... 85 Special Help Features ...... 86

Windows Script Host and Windows PowerShell Features ...... 87 Windows Script Files ...... 87 Starting a WSF ...... 87 WSF Workspace ...... 88 WSF Properties ...... 90 WSF Code ...... 91 Windows Script Components ...... 91 Starting a WSC ...... 92 WSC Workspace ...... 92 WSF Code ...... 94 WSC Properties, Methods, and Events ...... 94 Using a WSC ...... 95 Windows PowerShell Snap-Ins ...... 95 5 Script Signing ...... 96 Windows Script Host TrustPolicy Settings ...... 96 Script Encoding ...... 97 WMI Wizard ...... 97 ADSI Wizard ...... 99 ADO Wizard ...... 101 Compiling (Packaging) Scripts ...... 101

Script Debugging ...... 103 Using External Debuggers ...... 103 Using the PrimalScope™ Windows Script Debugger ...... 104 Installation and Security ...... 104 Working with Breakpoints...... 105 Debugging Scripts ...... 106 Adding Arguments ...... 107 Examining Variables and Object Properties ...... 107 Evaluating Expressions ...... 108

Built-in FTP Client ...... 110

Packaging Scripts using the Evolved Script Packager™ ...... 112 Applicability ...... 113 General Settings ...... 114 Folders ...... 115 Security Settings ...... 116 Files ...... 117

The Remote Script Execution Engine™ ...... 118 RSEE Deployment ...... 119 Identity ...... 120 TCP Port ...... 120 Domain Tips ...... 121 Using RSEE ...... 122 RSEE Restrictions ...... 126 RSEE Notes ...... 128

The Visual Query Builder ...... 129 Creating a Database Connection ...... 130 Creating a Query ...... 131 Testing and Using Queries ...... 132 Customizing the Query Builder ...... 133 6 Working with XML Documents in the Visual XML Editor ...... 134 Using the Visual XML Editor ...... 135 Repeating Elements ...... 136

Scriptable COM Components ...... 138 INI File Access Component ...... 139 Process Control Component ...... 141 File Dialog Component ...... 142 Login Dialog Box Component ...... 145 ASP Debugging Component ...... 146

Automating PrimalScript ...... 148 .psCmd files ...... 148 psCommands ...... 149

Keyboard Shortcuts ...... 156 Cursor movement ...... 156 Selection functions ...... 157 Clipboard functions ...... 157 Find Shortcuts ...... 157 Script Shortcuts ...... 158 Editing Shortcuts ...... 158 Window navigation ...... 159 Bookmark shortcuts ...... 159 Project shortcuts ...... 159 File shortcuts ...... 159 PrimalSense keys ...... 160 Outlining keys ...... 160 Internal Script Debugger keys ...... 160 Miscellaneous ...... 160

Index ...... 161

7 Chapter 1 Introduction

PrimalScript 2007 is the industry’s most mature, most feature- filled, and most popular script and code editor. Focused firmly on the needs of systems administrators, Web developers, Macromedia® Flash® developers, and others working with script and other advanced languages, PrimalScript provides everything you need to become more efficient and more effective in your scripting and coding efforts.

PrimalScript Editions PrimalScript 2007 is available in three distinct editions: • PrimalScript Standard is the entry-level PrimalScript product, providing advanced features such as PrimalSense, syntax color-coding, advanced formatting, code wizards, and support for dozens of scripting languages. • PrimalScript Professional adds high-end features such as integrated debugging of Microsoft® Windows® Script Host scripts, PrimalDiff, script packaging, and more. • PrimalScript Enterprise is the premier edition, offering support for Microsoft .NET Framework projects, remote scripting, a graphical query builder, and more.

8 • PrimalScript Universal is a special package including PrimalScript Enterprise, training resources, additional SAPIEN software, scripting tools and utilities, and more.

9 What’s New in PrimalScript 2007? PrimalScript 2007 introduces a variety of new features designed to enhance your productivity: • A brand-new user interface, including dockable panes, tab groups, and other enhancements. You can completely rearrange the PrimalScript UI to work the way you want to. • An enhanced script packager, giving you the ability to package VBScript, JScript, Windows PowerShell, and HTML Application files into standalone executables that run under alternate credentials. VBScript and JScript files can also be run more securely by using the SAPIEN Script Host, which runs entirely in memory and without the use of temp files. • An all-new Visual Query Builder, offering a vastly improved drag-and-drop means of building complex SQL language queries for your scripts. • An enhanced Find in Files feature, offering an improved results display that makes examining even a large set of results easier and more efficient. • An ActiveX Data Objects Wizard, which is integrated into PrimalScript’s Database Browser. Use it to quickly generate VBScript code that makes working with databases fast and easier—including the use of PrimalSense code hinting and completion! • An updated macro language that allows you to write .psCmd scripts—essentially, it’s a way to script PrimalScript itself, to automate various tasks. Nearly every feature and function in PrimalScript is accessible through the psCommand language.

10 Technical Support Your license for PrimalScript includes complete technical support. To obtain support, visit the SAPIEN Web site at www.sapien.com. SAPIEN also offers support contracts which include product upgrades, service level agreements for technical support responses, and more. Ask your SAPIEN representative about the available offerings.

Stay Up to Date PrimalScript is continually improved, both to remove software bugs and to add and improve product features. PrimalScript is designed to periodically check with the SAPIEN Web site for updated versions of itself, and to notify you when updated versions are available. We recommend always installing the latest available version of PrimalScript to ensure that you’re taking advantage of the latest features, functionality, and product stability.

You can check your product’s version and build number by selecting About from the Help menu. The last several digits in the version number are the build number, and signify a minor product update.

11 Chapter 2: Getting Started

When PrimalScript runs for the first time, it performs two very important tasks that help set its initial configuration. The first step scans your system for useful, scripting-related tools and adds them to the Tools Browser Browser. The second optimizes the PrimalScript user interface for the type of scripting that you do the most.

Security Before you begin, understand that many PrimalScript features require local Administrator access to your computer. For example, the following features all require administrative access: • Enumerating WMI namespaces and classes (for the WMI Explorer and WMI Wizard) • Debugging scripts • Changing the Windows PowerShell ExecutionPolicy • Changing the Windows Script Host TrustPolicy • Scanning for new command-line tools • Accessing links from within the Info Browser This is only a partial list; other features may also require administrative access. Also, installing PrimalScript usually requires administrative access if you plan to add local firewall

12 exceptions for the Remote Script Execution Engine or the ASP Debugger. When running PrimalScript on Windows Vista, the operating system’s User Account Control (UAC) feature can prevent these features from running or installing correctly. We recommend that you configure PrimalScript to always run as administrator if you are using UAC on Windows Vista. To do so: • Right-click the PrimalScript shortcut or executable and select Properties. • Select the Shotcut tab • Click Advanced • Select the Run as administrator checkbox • Click OK, then OK. Now, Windows Vista will display its UAC warning or authentication dialog each time you run PrimalScript. Alternately, you can right-click PrimalScript and select Run as Administrator each time you want to open PrimalScript. With UAC out of the way up front, it will not interfere with any of PrimalScript’s functions. You should install PrimalScript by right-clicking the installer package and selecting Run as Administrator. This ensures that PrimalScript installs with the privileges necessary to properly configure advanced components such as the Remote Script Execution Engine.

Firewall Considerations PrimalScript Enterprise installs a small service to support the Remote Script Execution Engine. This will result in a firewall warning as the service attempts to open the port it listens on. For more information, consult the chapter on the Remote Script Execution Engine feature. All editions of PrimalScript occasionally attempt to access a text file located on the sapien.com or primalscript.com Web sites. This text file contains the version number of the current version of

13 PrimalScript; your firewall software may warn you when PrimalScript attempts to read this file for the first time. PrimalScript does not transmit any personally-identifiable information when making this check—its sole purpose is to notify you when updates are available. PrimalScript also accesses the Web to display its product registration page (after initial installation), and to display Web pages when you click on links in the Info Browser. If you configure PrimalScript to use its ASP Debugging feature (covered in the Scriptable COM Components chapter), your firewall software may alert you when PrimalScript initially opens the port required for debugging communications.

Scanning for Tools This step is performed automatically the first time PrimalScript runs. However, if you install additional tools—such as database management tools, language compilers, and so forth—after PrimalScript runs for the first time, you’ll need to manually re-scan so that PrimalScript can pick up your newly-installed tools and add them to the Tools Browser (of course, you can also simply add new tools to the Tools Browser on your own—Chapter 5 describes how to do so). To re-scan for tools, first make sure that PrimalScript is not running. Open your PrimalScript installation folder. Normally, this is \Program Files\SAPIEN\PrimalScript edition (where edition is the edition of PrimalScript that you own). Locate ToolScan.exe and double-click the file to run it. Click the Scan button to begin the scan, which should only take a few moments. After the scan completes, click Close to close the tool. Re-open PrimalScript and your Tools Browser should be up- to-date.

Optimizing the User Interface Because PrimalScript provides functionality specific to so many scripting technologies, you may find the user interface to be a bit overwhelming at first. To help make it more manageable, 14 PrimalScript includes a User Interface Wizard that hides portions of the user interface—such as toolbars—and sets certain defaults, so that you’re only looking at elements related to the type of scripting you do.

PrimalScript doesn’t remove any user interface elements; it merely hides the ones you probably won’t need. You can always make toolbars (for example) visible again, by simply right- clicking any visible toolbar and selecting the other toolbar(s) you want to see.

If you change the way you script in the future, you can re-run the Wizard to re-optimize the user interface for your new work style. To do so, open the Tools menu and choose Select your Role. The Wizard asks you to indicate your role, based on a list of commonly-used job roles that have specific functionality built into PrimalScript. Next you’ll customize the PrimalScript Browser areas. Various Browser windows are pre-selected to appear on the left and right side of the screen, based upon the job role you selected. Finally, you’ll customize the file types that appear within PrimalScript’s various file management dialog boxes. Again, only those file types related to the role you selected are initially checked.

Registering Your Product After PrimalScript is up and running, be sure to register it. To do so, select Register Product from the Help menu; your default Web browser will open to the registration page. Registration is required in order to obtain any customer service or technical support benefits, and it takes only a few moments to complete.

15 Registration also provides you with access to special offers, including preferred pricing on upgrades.

Removing Your License Need to remove your PrimalScript license so that you can use it on another computer? Select Remove License from the Help menu. PrimalScript will immediately become an “expired trial,” and your license key will be available for use on another computer.

Troubleshooting and Diagnostics PrimalScript includes a number of command-line switches designed for troubleshooting and technical support use. You may be instructed to use these by a SAPIEN Technologies support engineer. So that you’re familiar with what they do, here they are: • /LOGSTART launches PrimalScript and creates a startup log in C:\PSSTART.LOG. • /HELPAUTHOR displays dialog or context-sensitive help ID numbers when you highlight language keywords and press F1. • /NOSPLASH launches PrimalScript without displaying its splash screen. Note that these are case-sensitive and must be typed in all uppercase. Other command-line switches are available but should only be run if you are instructed to do so by SAPIEN Technologies; many of these can permanently damage your installation if used improperly.

16 General Command-Line Switches PrimalScript includes a number of general-purpose command-line switches: • /s filename launches PrimalScript and forces the specified filename to be opened as a PWS (workspace) file. • /w filename launches PrimalScript and forces the specified filename to be opened as a WSF file. • /c filename launches PrimalScript and forces the specified filename to be opened as a WSC file. • /t filename launches PrimalScript and forces the specified filename to be opened as a text file. • /b filename launches PrimalScript and forces the specified filename to be opened as a binary file. • Filename /l line launches PrimalScript, opens the specified file, and jumps to the specified line number.

17 Chapter 3: Basic Orientation

Before you get started with PrimalScript, let’s quickly review the names and locations of the major user interface elements. The figure below illustrates the major user interface elements.

Names and locations of major PrimalScript user interface elements

18 Because PrimalScript displays certain user interface elements according to Windows visual themes, the exact appearance of PrimalScript on your system may differ.

Most of these major areas can be resized or even hidden entirely to meet your needs. Each of the Browser areas, for example, can be independently hidden, toolbars can be individually hidden, and the Browser areas can be resized. Toolbars can also be moved around to meet your specific preferences. PrimalScript incorporates multiple toolbars to provide faster access to various features. In many cases, you’ll simply show and arrange the toolbars you use most, or those relevant to a particular project. To change the toolbars which are displayed, simply right-click any toolbar which is currently displayed. You can then show or hide toolbars as required.

The File Toolbar

The File toolbar provides basic functions for file management: • Create a new file • Open a file • Save the current file • Save all open files • Mail current file as an attachment • Print the current file • Print preview of the current file • Context-sensitive help

19 The Debugging Toolbar

The Debugging toolbar is designed to work with the built-in PrimalScope™ Windows Script Debugger. It provides functions for setting breakpoints and for operating the debugger while the script is running. PrimalScope™ is only available in PrimalScript Professional and Enterprise. PrimalScript Standard can utilize the Microsoft Script Debugger (not included) through the Script toolbar.

• Show next statement • Set next statement • Step into • Step • Step out of • Run to cursor • Start debugging • Restart debugging • Stop debugging • Pause debugging • Set/remove (toggle) breakpoint • Clear all breakpoints • Enable/disable (toggle) breakpoint • Disable all breakpoints

For more information on using PrimalScope™, refer to Chapter 12.

20 The Edit Toolbar

The Edit toolbar provides access to frequently-used editing functions. Note that many of these functions are also available through keyboard shortcuts, making them even more convenient and accessible. • Cut selection to Clipboard • Copy selection to Clipboard • Paste selection from Clipboard • Undo last action* • Redo last action* • Outdent selection • Indent selection • Create persistent foldable region • Change selection to comment • Uncomment selection • Match braces

*Undo and Redo utilizes PrimalScript’s infinite undo feature. PrimalScript maintains an extensive history of all editing actions in your script, and persists that history along with the file (provided the file is stored on the NTFS file system). This allows you to undo actions which were made days or even months in the past.

21 The Find Toolbar

The Find toolbar provides access to PrimalScript’s extensive built- in search and replace capabilities. • The drop-down list displays recent find operations • Find • Find previous • Find next • Find in files • Replace • Replace in files

The View Toolbar

The View toolbar provides quick access for configuring PrimalScript’s view options. • Show/hide hidden characters (such as spaces or line returns) • Toggle line number display • Toggle column ruler • Toggle hexadecimal display mode • Cascade open windows • Vertically tile open windows • Horizontally tile open windows • Global bookmarks

22 • Toggle bookmark • Previous bookmark • Next bookmark • View document in Web browser • Enable/disable source control connection

For more information on source control integration, please read Chapter 9.

The Script Toolbar

The Script toolbar provides access to commands commonly used in Windows scripting. • The drop-down list controls the active project • Execute project commands • Run job (only active for WSF files) • Debug job (in external debugger, not PrimalScope™; only active for WSF files) • Register component (for WSCs) • Unregister component (for WSCs) • Generate type library (for WSCs) • Check script syntax and/or compile/package Packaging of Windows scripts, using the Evolved Script Packager™ (ESP™), is available only in PrimalScript Professional and Enterprise.

23 The exact action taken by the check/compile button depends on the language you’re working in. For languages with a compiler (like C++), the compiler will be launched. For languages supported by the Evolved Script Packager, the script will be packaged.

• Run script • Debug script (in external debugger, not PrimalScope™) • Stop debugging • Run script on remote computer (Remote Script Execution Engine™) • Sign script • Execute code Wizard • Package script (using ESP™)

The PrimalSense Toolbar

The PrimalSense toolbar provides access to PrimalScript’s built-in PrimalSense features. • The drop-down list allows you to quickly jump to a defined function or subroutine within your script. • Display the PrimalSense pop-up completion list • Display parameter information • Complete the current word • Open matching files 24 Most PrimalSense features will function automatically, and are also accessible via keyboard shortcut, making them more conveniently-accessible than the toolbar.

The HTML Toolbar

The HTML toolbar provides access to HTML formatting functions. • Quickstart – set key properties for a new HTML page • Insert HTML anchor • Insert image • Comment • Insert entity (defaults to non-breaking space) • Font color • Color selection • Boldface • Italics • Underline • Left align • Center align • Right align • Full (justified) align

25 The FTP Toolbar

The FTP toolbar provides access to PrimalScript’s built-in FTP client. Note that this should not be confused with the more simplistic FTP commands available on PrimalScript’s File menu. The built-in FTP client is only available in PrimalScript Professional and Enterprise. The simplified FTP commands on the File menu are available in all editions.

• The drop-down list box allows you to select a previously-defined FTP connection. • Create a new FTP connection • Login • Refresh display • Create a new folder • Go up one level in folder hierarchy • Display files as icons • Display files in a detailed list • Upload selected file • Download selected file

For more information on using the built-in FTP Client, please read Chapter 13.

26 The Source Control Toolbar

The Source Control toolbar provides access to PrimalScript’s source control integration capabilities. Note that PrimalScript does not include source control software, but rather provides integration with industry-standard software like Microsoft Visual SourceSafe. PrimalScript Enterprise includes the ability to connect to CVS and Subversion-compatible source control solutions.

• Get latest version of file • Check file out • Check file in • Undo last check out • Add file to source control • Delete file from source control • Show version history • Show differences between file versions • Show file properties • Refresh source control status

For more information on using source control integration, please read Chapter 9.

27 The Build Toolbar

The Build toolbar provides functions for working with the current project and building (or compiling, as appropriate) it. • The first drop-down lists selects the current project. • The second drop-down list selects the build configuration (such as Debug or Release) • Execute project commands • Backup project • Build project • Rebuild project • Stop project build • Run project • Debug project (uses external debugger, not PrimalScope®) • Stop project

The Internet Toolbar

The Internet toolbar provides access to PrimalScript’s integrated Web browser. • Back • Forward • Stop • Reload • Home

28 • The drop-down combo box can be used to type a URL or select a previously-visited URL

PrimalScript instantiates Microsoft’s Internet Explorer within the PrimalScript window.

The Info Toolbar

The Info toolbar provides functions for working with the Info Browser. • Synchronize contents • Previous (in contents) • Next (in contents) • Search • Result list

For more information on the Info Browser, please read Chapter 6.

Now that you’re familiar with the location, visual appearance, and names of these various user interface elements, you can start learning how PrimalScript makes scripting and software development easier and more efficient.

The XML Toolbar

The XML Toolbar works in conjunction with PrimalScript’s Visual XML Editor. 29 The Visual XML Editor is only available in PrimalScript Enterprise.

• Add an XML element • Insert an XML element • Delete an XML element • Repeat an XML element • Add an XML attribute • Delete an XML attribute • Validate the XML document • Apply an XML stylesheet

Working with Tabs and Panes PrimalScript’s user interface consists of two major elements: • Tabs – such as the tabs used to edit documents in the code editor. Tabs can be grouped within the central window area. • Panes – such as the browser panes and output pane. Panes can be pinned, which keeps them open, or allowed to auto-hide. Any documents that you open appear as colored tabs. Right- clicking a tab gives you a context menu with a number of options. For example, you can create new vertical or horizontal tab groups by selecting the appropriate option from the context menu. With a new tab group open, you can drag tabs between groups to arrange them as desired.

Arranging tabs into horizontal groups

If you frequently work with a particular set of files as a group, you can save them in a tab group. From the File menu, select Save open files as group. All currently-opened files will be saved into a file which, if double-clicked in Windows Explorer, will re-open those same files in PrimalScript. Document tabs can never become panes; they are always tabs. However, panes—the Browser panes, Output pane, and so forth—can be undocked from the main PrimalScript window (allowing them to float, even across multiple monitors), or they can be made into tabs. To undock a pane, simply click on its title bar, hold the mouse button, and drag the pane to its new location. To re-dock it, drag it again, this time to one of the docking symbols that appears while you are dragging the pane.

Docking panes

By right-clicking a pane’s title bar, you can turn it into a tabbed document. This allows it to be placed within a tab group. To return it to being a dockable pane, right-click the tab and select Tabbed Document from the context menu.

Selecting a Layout and Color Scheme By selecting Options from PrimalScript’s Tools menu, you can access PrimalScript’s Application>General settings, where you can select a visual layout and color scheme for PrimalScript.

Application>General settings

You can also select a tab style for use with tabbed documents. Once you’ve selected your preferred user interface settings, you can save them to an XML file using the Save Interface Settings… button. You can then share this XML file with others, allowing them to use the Load Settings… button to load your PrimalScript settings into their licensed copy of PrimalScript.

33 Chapter 4: Core Editor Features

PrimalScript is more than just a script editor; it’s actually a complete environment, including dozens of built-in tools and functions to make scripting and software development more efficient. However, at the heart of PrimalScript is the industry’s most powerful and flexible code editor. While it’s easy to start using PrimalScript’s editor without any training, a number of its most efficient and effective features can be easily overlooked. In this chapter, you’ll learn about all of the core editor features within PrimalScript, as well as a number of tips for using PrimalScript more efficiently.

Editing Aids PrimalScript includes a number of editing aids that make editing scripts and code easier.

Line and Column Numbering PrimalScript provides optional line numbering and a column ruler, making it easier to navigate to the desired line and column. The current line and column are also displayed in PrimalScript’s status bar. Line numbering, the column ruler, and the status bar can be enabled or disabled from the View menu. Line numbering and the column ruler can also be enabled or disabled from the View toolbar.

Line and column positioning in the editing window

Bookmarks and Jumping Bookmarks make it easier for you to return to specific sections of your script. Bookmarks appear as colored blocks in the margin of the editing window.

Bookmarks

There are a number of ways to toggle a bookmark on or off, with the cursor located on the line where you want the bookmark, or where a bookmark exists: • Click Toggle Bookmark from the View toolbar. • Select Toggle Bookmark from the View menu.

35 • Press Ctrl+F2. You can also quickly jump to the previous or next bookmark: • Click the appropriate button on the View toolbar. • Select the appropriate option on the View menu. • Press F2 (next) or Shift+F2 (previous). Aside from bookmarks, PrimalScript provides a few other shortcuts to quickly move to different locations in your script. These functions are accessible from the View menu, or using keyboard shortcuts: • To jump to a specific line number, press Ctrl+L. • To jump to the last position where you made an edit (in other words, where you typed or deleted something), press Ctrl+E.

Character Display Normally, PrimalScript does not display hidden characters like spaces, tabs, and carriage returns. However, by selecting View Hidden Characters from the View menu or toolbar, you can display these characters. Doing so can make precision formatting easier.

Displaying hidden characters

You can also have PrimalScript display a document in hexadecimal mode, by selecting Toggle Hexadecimal Display from the View menu or toolbar. This mode can make working with binary documents easier, since you can work directly with the raw data, even if that data isn’t normally viewable in a text editor.

Viewing hexadecimal data

Clipboard Integration In addition to the usual Copy, Cut, and Paste features (accessible via the Edit menu, Edit toolbar, or standard Windows keyboard shortcuts), PrimalScript also provides advanced integration with the Windows Clipboard. You can select Append to Clipboard from the Edit menu to append the currently-selected text into the Clipboard, without replacing whatever is currently on the Clipboard. This is an excellent way to piece together data from various portions of a document (or various documents), and then paste the final concatenated result. PrimalScript also provides access to the Clipboard Ring. This Ring stores the last several cut or copy operations, and pressing Ctrl+Shift+V (or selecting Cycle Clipboard Ring from the Edit menu) cycles through the various pieces of data on the Clipboard, pasting them into your document. Repeatedly pressing Ctrl+Shift+V cycles each piece of data into your document in turn.

Code Folding Code folding is a technique that allows you to collapse or expand sections of your code. Collapsing sections of code in a long script makes it easier to focus on the section you’re currently working with.

Automatic Regions PrimalScript automatically creates foldable regions from declared functions and subroutines.

Automatically-created foldable region

When collapsed, PrimalScript properly displays line numbering, accounting for the lines contained within the collapsed (or folded) region. This ensures that line number-based error messages and other information remain accurate.

Proper line numbering through a folded region

Temporary Regions PrimalScript automatically creates temporary foldable regions whenever you select a contiguous block of text. These temporary regions can be expanded and collapsed, but are not persisted when the file is closed and reopened.

Temporary foldable region

Named, Persistent Regions You can create a persistent region—one which is maintained even if the file is opened and closed—by clicking the Create Region button on the Edit toolbar. This creates a named region with the name “Persistent fold region.” You can edit the name to whatever you like.

Named foldable region

Named regions are convenient because, when folded, the name remains visible, reminding you what the region contains.

Folded named region

You can create a named region manually simply by specifying the #region and #endregion keywords on comment lines within your script, using the proper commenting syntax for your scripting language (VBScript is shown in these examples).

Creating named regions in a script

Manipulating Regions The Edit > Outline submenu contains commands for manipulating foldable regions. 39

Edit > Outline submenu

Search and Replace PrimalScript includes extensive, powerful search and replace features, allowing you to revise a file’s contents—or even multiple files’ contents—quickly and easily.

Basic Search Basic searching is most easily accomplished form the Find toolbar, by selecting Find from the Edit menu, or by pressing Ctrl+F. When using the toolbar, simply type your search text and click the Find toolbar button. You can apply additional options by pressing Ctrl+F and using the Find dialog.

Find dialog

Here, you can use common search criteria such as whole word matching and case matching, as well as searching forward or backward. The Find dialog will stay open while you edit your script, and you can click Find Next to find the next occurrence of your search string. Clicking Mark All will place a bookmark at each location where your search string occurs; you can then use F2 and Shift+F2 to move back and forth between bookmarks.

40 Basic Search and Replace The Replace dialog is displayed by clicking the appropriate button in the Find toolbar, selecting Replace from the Edit menu, or pressing Ctrl+H.

Replace dialog

Options similar to those on the Find dialog exist. You can also specify that the replace operation affect only the selected code, only the active document, or that it be conducted across all open documents.

The Replace control characters checkbox allows you to type control characters (such as /n for a carriage return) and have that character inserted in the replacement operation.

Regular Expression Searching PrimalScript’s Find and Replace functionality includes the ability to search for regular expressions. For example, the regular expression “/^\s[ \t]*$/” matches a blank line. This regular expression (or any other) can be used in either the Find or Replace dialogs, simply by selecting the Regular expression checkbox.

41 You can learn more about regular expressions and their syntax at http://www.regular- expressions.info/tutorial.html.

Searching and Replacing in Files PrimalScript can perform detailed search (and replace) operations across a number of files, without requiring you to first open those files in PrimalScript. To begin, select either Find in Files or Replace in Files from the Edit menu (or click the appropriate button on the Find toolbar).

Find and Replace in Files dialog

You’ll need to enter the text to search for (and, in a replace operation, the replacement text), and indicate which folder to look in. You have the option of having PrimalScript also process files in subfolders, and you can indicate which file types should be included in the operation. Results are displayed in a dockable pane. Each file is shown as a single item in the pane, and you expand that item to see each line where matching text was found within the file. Double-clicking a match opens the file and jumps directly to that line; the results pane turns that match’s icon green to indicate that you’ve reviewed that particular match.

Find in Files Results Pane

Conversion Features PrimalScript includes a number of conversion features that can help make data manipulation within your script easier. These features are accessible from the Convert submenu on the Edit menu.

Convert submenu

43 Generally speaking, you convert by selecting the text that you want to convert, and then selecting the appropriate conversion feature (or pressing its keyboard shortcut, where available). Conversion functions include: • Between uppercase and lowercase • Case inversion (switch upper to lower and vice-versa, all in one operation) • Converting numeric text to decimal, octal, or hexadecimal • Between ANSI and OEM-style characters • Converting spaces to tabs, or vice-versa • Encoding or decoding information for URLs (for example, “WScript.Shell” would be URL encoded to “WScript%2EShell”.

Formatting Features PrimalScript’s formatting features are located on the Format submenu of the Edit menu.

Format submenu

These features are most commonly used in text and XML files, and require you to select a section of text or XML before selecting the formatting feature. The features include: • Inserting line numbers at the start of each line.

Line numbering

• Inserting bullets at the start of each line.

Bulleting lines

• Sorting lines in ascending or descending order. • Reformatting XML (only available in XML files).

XML – before reformat

XML – after reformat

45 PrimalSense™ PrimalSense is SAPIEN’s brand-name for our powerful, flexible code-hinting and code-completion feature.

PrimalSense is similar in functionality to features such as Microsoft IntelliSense, which is found in Microsoft’s Visual Studio products.

PrimalSense works automatically in most cases, providing several distinct features: • Syntax coloring PrimalSense automatically colors your code syntax to help make literals, statements, comments, and other elements stand out more clearly.

• Case correction When appropriate, PrimalSense automatically corrects the case of intrinsic statements, variable names, and other elements, helping your code to appear more professional. • Member lists When working with classes or objects, PrimalSense displays pop-up lists containing available members, such as methods and properties. In many cases, PrimalSense can provide “deep” assistance, helping you work with sub-objects and their members, as well.

• Variables PrimalScript automatically attempts to complete variable names, function names, and the names of other elements from within your script, to save you from having to type the full names. • Class/object lists When using a statement like CreateObject() in VBScript, PrimalSense provides a pop-up list of available classes or objects, helping to complete your statement more quickly. Simply type or use the arrow keys to display your desired selection, and then press Tab to insert it into your script.

• Syntax hints PrimalSense provides pop-up “tool tips” to help remind you of proper syntax for objects, intrinsic keywords, and defined subroutines, functions, and classes.

• Automatic Syntax Checking For selected scripting languages, PrimalScript is able to automatically pass your script to the script engine as you write. Any errors reported by the script engine will be underlined in red, calling your attention to the problem. Note that this feature is entirely dependent upon the script engine; for example, the VBScript engine will only report the first error it finds.

By default, PrimalSense doesn’t begin working until you’ve typed a few characters from a recognized keyword, object variable name, or other element. However, if you want immediate help, simply press Ctrl+Space. Or, type the first couple of letters of what you’re looking for, and then press Ctrl+Space. PrimalSense will immediately display a list of intrinsic keywords, defined functions, variables, and much more, helping to get you started.

You’ll also notice that PrimalSense is able to help complete variable names, function names, and the names of other elements. Typically, PrimalSense will jump in after you’ve typed about 3 characters, helping you to complete whatever you’re typing in less time. Because PrimalSense features Optimized Parsing Technology™ (OPT™), you’ll never have to wait for it to display the help you need—it works instantly.

48 You can customize PrimalSense’s behavior. Select Options from the Tools menu in PrimalScript, and open the Text Editor>PrimalSense section. Here, you can disable specific PrimalSense features, such as auto-listing members, auto case correction, live syntax checking, and more.

Windows PowerShell users may notice a slight delay when opening a Windows PowerShell script for the first time in each editing session. This delay is PrimalScript opening the PowerShell engine; you can have PrimalScript do this automatically at startup by adjusting the options in the Text Editor>PrimalSense options section.

Oops Resilience™ PrimalScript provides two distinct, but related features for helping you undo mistakes.

Infinite Undo™ By default, PrimalScript maintains a nearly infinite “undo list,” allowing you to press Ctrl+Z (or click the Undo button in the Edit toolbar, or select Undo from the Edit menu) to progressively undo editing actions in your files. Also by default, PrimalScript stores this “undo list” along with your file, provided the file is stored on a Windows NTFS volume (the “undo list” is stored in a separate stream of the file, which is why NTFS is required). That means you can open the file months later and continue undoing past actions.

49 Recycle Bin The Recycle Bin, located on the PrimalScript status bar at the bottom of the window, stores all deleted text segments. You can review these deleted segments and remove them from the Recycle Bin, copy them to the Clipboard, or insert them back into your script.

The Recycle Bin

The Recycle Bin is not per-file; it is a global Recycle Bin containing everything you’ve recently deleted. However, the Recycle Bin does retain its contents between PrimalScript sessions. To empty it, simply right-click it and select Empty. You can also right-click it and select Properties to configure its behavior. You can configure the minimum length necessary for deleted items to be added to the Recycle Bin (shorter items will be discarded and not added to the Recycle Bin), as well as the maximum length of items (larger items will be discarded) and the maximum number of items the Recycle Bin will store.

File History PrimalScript also has a File History feature. This feature acts as an entry-level substitute for a full source control solution. Essentially, each time you save a file, the old copy is stored in a

50 special “file.history” file in the same folder (all scripts in a given folder share the same “file.history” storage). At any time, you can select Show file history from the File menu to review past versions of the file, and even retrieve those past versions.

File History

The biggest thing to remember about File History is that it is only effective when your script remains in the same folder. If you move a script to a different folder, it will no longer be associated with the correct “file.history” storage, and will appear to have “no” file history. You can remedy this by immediately moving the script back to its original folder, where PrimalScript will be able to locate the correct “file.history” storage.

Do not delete the “file.history” file created by PrimalScript. This file contains the file history (or backups) for all files in the same folder.

51 Chapter 5: Browser Panes

PrimalScript includes two Browser areas, which can be displayed or hidden according to your preference. The Left Browser Pane contains the following Browser windows: • Workspace Browser • Type Library Browser • File Browser • Tools • HTML Navigator • Resources Browser While the Right Browser Pane contains these Browser windows: • Class Browser • Info Browser • Snippets Browser • Database Browser • Tasklist Browser

You can rearrange these dockable panes; the terms “Left” and “Right” refer to their default position within the user interface.

52 The Info Browser The Info Browser displays an organized list of links to Web sites and other documents. Selected documents appear within PrimalScript, using its embedded Web browser. You can right- click within the Browser to create new objects. You can create folders, links to help files, links to HTML files or Web pages, and links to PDF files. This allows you to keep all of your reference material handy, ready to pop up at a moment’s notice. You can also search for items within the Browser, as well as import or export Browser items. Again, simply right-click any item to display these options in a context menu.

The Workspace Browser The Workspace Browser helps you keep projects organized. This Browser displays all of the items associated with a project, including supporting files. You can right-click various elements to work with them, such as modifying their properties. The Workspace Browser can contain multiple projects, allowing you to work with different projects at once. Each project is listed in a separate portion of the Browser’s hierarchical tree. For most project types, you can right-click the project itself to publish it. The exact options available when right-clicking a project depends on the type of project; for example, Windows Script Host WSF and WSC projects offer different options than ASP or ActionScript projects.

The Tasklist Browser The Tasklist Browser automatically creates a “to do” list based on comments you place in your scripts, and on manually-created tasks you create for yourself. Tasks listed under Project Tasks are picked up from comments in your code, such as the following:

Comments that create Project Tasks

You can change the comment tags that the Tasklist Browser looks for: Open the Options menu from the Tools menu, and select Environment>Task List. You can add, modify, or delete any of the “tokens” (such as the default TODO and DONE tokens) that the Tasklist Browser scans for. You can double-click any task in the Tasklist Browser (under Project Tasks) to be taken directly to the corresponding comment in your code. Right-clicking Personal Tasks allows you to create new task categories; you can right-click a category to add a task to it. Double-click a personal task to change its properties. You can also right-click a category to change its name and perform other tasks.

The Type Library Browser This Browser provides access to all registered Component Object Model (COM) objects on your computer, allowing you to explore their interfaces and members. Because this Browser has been designed to provide the maximum amount of useful information (unlike other type library browsers you may have used, which often restrict the information you can see), learning to use the Browser requires some practice. Understanding the iconography used in the Browser can help.

You’ll see this icon next to the ProgID for the component. The ProgID is what you’d use in a CreateObject() or other statement to instantiate the component.

This icon refers to an enumeration, which is a set of values that have been assigned easier-to- remember names.

54 This icon represents an interface, which is generally a specific class or object that your script can work with. The Microsoft Scripting Runtime, for example, is a library containing interfaces for the FileSystem, TextStream, Dictionary, File, Folder, and other objects.

This icon represents a member, which is a property, method, or event within an interface. For example, taking the common FileSystemObject (which is the IFileSystem interface of the Microsoft Scripting Runtime), you’ll find a number of members, such as BuildPath and GetFolder. Reading member definitions takes some practice, too. Here’s an example:

The first word in each definition is the data type that the member returns: • BSTR is a string (technically, a binary string, but string is what really matters) • boolean is a True or False value • IDrive and IFile indicate that these members return an object, which are defined by the IDrive and IFile interfaces. The next word is the member name itself: GetTempName(), DriveExists(), and so forth. Finally, within parentheses, you’ll see the input parameters, or arguments, or each member. For example, GetTempName() doesn’t accept any arguments. DriveExists() accepts one input argument, which is a string (BSTR). Here’s another example: 55

In this example, the GetSpecialFolder() member returns a Folder object (represented by the IFolder interface). It accepts one input argument, which is a SpecialFolderConst. You can locate these constants in the appropriate enumeration. The DeleteFile() member doesn’t return anything—that’s why its return data type is listed as void. It accepts two input arguments: One is a string, and the other is a Boolean True/False value.

Remember, you can see the names of these input arguments by using PrimalSense. Just start using the method in your script, and the list of arguments will pop up in a tool tip.

The Resources Browser This browser allows you to explore other scripting resources, such as software, training, and more.

The Class Browser This Browser lists all of the classes defined in your current project. This list is read-only, and updates automatically as you add or remove classes to and from your project.

The File Browser This Browser provides access to the local file system on your computer. You can drag files out of this Browser into the code window in order to edit the files.

56 The Tools Browser This Browser provides access to commonly-used tools of various types. It is initially populated during PrimalScript’s installation, based on the software found on your computer. You can customize the Browser to meet your needs. To customize the Browser, simply right-click it. You’ll be able to add groups, add and remove tools, change the way tools are displayed, remove groups, and rename groups. This Browser provides a convenient place for any tools you may need while working on projects.

The Snippets Browser The Snippets Browser provides access to a library of built-in code snippets. To insert a Snippet into your code, simply drag it from the Browser into the code editor. Or, in the code editor, type the Snippet’s name and press Ctrl+J. Note that Snippets are language-sensitive: When using the Ctrl+J technique, only Snippets in the same language as your current script file will be used. You can right-click an item in the Browser to add a new folder or subfolder, or to add a new Snippet. You can also highlight code in the code editor, right-click the highlighted code, and select Save as Snippet to save the code as a new Snippet. Snippets are a great way to dramatically speed up scripting time by never having to write the same script code twice. Instead, save commonly-used code as Snippets, where it can be easily reused.

SAPIEN offers add-on packages of Snippets for various languages and tasks. Visit www.ScriptingOutpost.com to explore the available packages.

57 By default, PrimalScript keeps its Snippets in its installation folder. However, by opening the Options dialog from the Tools menu, you can go to the Environment>Directories section, where you can specify an alternate path—including a UNC—for your Snippets. A UNC path allows you to share a common Snippets library with your coworkers.

The HTML / XML Navigator Browser This Browser presents a hierarchical view of HTML or XML documents, allowing you to view the document structure in an ordered, organized fashion. You can click on any element within the tree to be instantly taken to that element’s location within the code editor. Icons within the Browser help you identify common elements such as anchors, tables, images, and so forth.

The Database Browser The Database Browser Browser is only available in PrimalScript Professional and PrimalScript Enterprise.

This Browser provides an easy way to explore the procedures, views, tables, and table or view columns within a database. To connect to a new database, right-click the Browser and select Create a new connection. You’ll be presented with a standard Wizard that allows you to connect to almost any ODBC or OLE DB database for which you have installed an appropriate driver or provider. For existing connections, right-click the connection object in the tree to view its properties, or to copy its connection string to the Clipboard (from there, you can paste it into your script). The Database Browser also provides access to the ADO Wizard. To begin using it, right-click a database table and select Generate VBScript Code.

The ADO Wizard

The Wizard can generate two types of code: Output code only is essentially a sample script that shows you how to retrieve information from your database using a SQL language query. A Recordset access class is a custom class inserted into your VBScript file. This class gives you full PrimalSense for working with the database objects.

PrimalSense for databases

59 Chapter 6: Project Management

PrimalScript projects help group related files and settings together. For example, all of the files associated with a Web site, including HTML, dynamic Web pages, and other files, might be consolidated into a project. Projects are very useful for managing sets of related files, such as the files associated with a Web site, an AJAX project, and ActionScript project, .NET projects, and more.

PrimalScript provides support for two special types of projects related to Windows scripting: WSF and WSC projects. These are covered in Chapter 10.

Starting a Project To begin a new project, select New > Project from the File menu. Then, select the type of project you’d like to create and provide it with a name and location. You can also create a new workspace for the project, or add it into the current workspace.

New Project dialog

There are many types of projects available; select the one that fits the type of work you’re doing. Note that most projects are designed to work only with files added through PrimalScript. That is, in order for new files to become a part of the project, they must be added to the project within PrimalScript itself. One exception to this is a Dynamic Folder Project. This project type will recognize files added to the project’s physical folder (on the hard drive), no matter how those files were added. This, for example, allows other users to add files to the folder, and PrimalScript will detect them and make them a part of the project for you. Dynamic Folder Projects are also useful when you’re creating files in another application, and then using PrimalScript to edit those files. A workspace is a collection of one or more projects, as defined by a .pws file. To re-open a workspace and all the projects it contains, simply double-click the .pws file in Windows Explorer (or, from within PrimalScript, select Open Workspace from the File menu).

Projects and Your Workflow One very valuable use for projects is in managing development workflow. Using projects, you can develop entirely on your local machine, ensuring that your work-in-progress doesn’t affect

61 production users. When you’re ready, the project can be deployed—by PrimalScript, and as a single unit—to a production server, where the project goes “live.” This contrasts with the common technique of editing files directly in production, such as on a Web server. With this technique, changes are seen immediately by users—but so are mistakes. Editing “live” files directly is a very poor development practice, and PrimalScript projects mean you don’t ever need to. Instead, projects allow you to work on your local machine, which serves as a development “sandbox” or testbed. You then deploy completed, tested, debugged files into production.

Workspace Management Workspaces form the basis for projects; all projects are contained within a workspace and a workspace can contain multiple projects. PrimalScript can only have one workspace open at a time. A workspace helps to organize related projects. For example, you might have one project for a Web site, and another for an ActionScript project that is used in the Web site. The workspace allows them to be open at the same time within PrimalScript. The File menu provides functionality for working with workspaces: • Open Workspace opens a previously-saved .pws file. • Save Workspace and Save Workspace as saves the current workspace to a .pws file. • Close Workspace closes the current workspace. • Recent Workspaces provides access to recently- opened workspaces. Workspaces can also include contacts (such as the developer responsible for the workspace). Simply right-click the workspace name in the Workspace Browser to add a contact. You can also: • Add new projects or insert existing projects into the workspace.

62 • Add configurations besides the default Debug and Release configurations. • Connect the entire workspace to source control and then add the entire workspace to your source control solution. • For workspaces under source control, perform checkin and check-out operations for the entire workspace.

Managing Project Items Projects can consist of multiple files and folders. The Project menu, or right-clicking on a project in the Workspace Browser, provides options for adding new items, adding existing items (that is, items which already exist but aren’t yet part of the project), and adding folders. You can right-click a project item in the Workspace Browser to remove it (without deleting it) from the project, or to permanently delete it. When adding new items (as opposed to existing items), the dialog box restricts you to those file types which are valid for the type of project you’re working on.

Projects and Source Control Projects can be managed as a unit through PrimalScript’s source control integration (source control integration must be configured first). Right-click the project name in the Workspace Browser to work with source control: • Connect to source control connects the project folder to a folder within your source control solution, providing a place for the project to reside within the source control solution. • Add to source control adds the project to source control. • Check in pending checks in all project files which have changed or not yet been checked in.

63 Individual files within the project can be checked in or out independently, as well, although checking files in together—as a project—helps to simplify file and source control management.

Project Properties Right-click the project name in the Workspace Browser and select Properties, or select Settings from the Project menu, to display the Project Properties dialog.

Project Properties dialog

A project’s Common Properties include its name (in the General section), as well as the items in the Commands section. This section allows you to define actions for specific verbs. For example, a Web project has a View command, which typically launches a Web browser to view the project. You can create additional verbs, or commands, as desired, and link each to the external executable that handles the command. For example, you might add a Compile command and link it to an external compiler that can compile your project. Project commands are also available on the Build toolbar, using the Project Commands button. The Debug and Release configuration sections each have a General section, which allows you to specify an external program

64 or URL to run or debug the project. They also have a Transfer section, which allows you to specify transfer options for publishing the project, either in debug mode or release mode. Transfer can be made via ftp or network file copy, and you can specify destination paths and credentials. You can also set the project mode to Local or Master, which will be discussed shortly. This separation between debug and release modes allows you to specify (for example) a local server for debugging the project, and a production Web server for releasing the project.

Managing Configurations You can modify the workspace itself to provide additional configurations aside from Release and Debug, or to modify those two names. Doing so can provide you with additional transfer destinations, if needed. For example, you might create an additional configuration called “Test.” This would allow you to have a Debug configuration where the project runs locally, a Test configuration that deploys to a test server, and finally a Release configuration that deploys to your production server. You can create as many additional configurations as you need. To do so, right-click the workspace and select Configuration Manager. Click New… to add a new configuration. When adding a new configuration, you can copy the configuration’s settings from an existing configuration, if desired—this is a good shortcut when the new configuration won’t differ much from an existing one. Then, go back into the project properties and you’ll see your new configuration listed.

Local Mode vs. Master Mode If you open a project’s configuration (any of them—Debug, Release, or one you’ve defined), you’ll notice a “project mode” setting. Projects can be set to either Local Mode or Master Mode. Local Mode, the default, allows you to work on all project files locally. Files aren’t published until you specifically do so (discussed in the next section). When you publish, files are 65 published to the target defined in the currently-selected configuration, meaning you can have a separate publishing target when you’re in Debug, Release, or another configuration you’ve defined. With Master Mode, changed files are automatically published to the defined target for the currently-selected configuration. How is this useful? Let’s say that you don’t have a Web server on your local computer, and while in Debug mode you want to test from a testing Web server on your local network. However, for Release, you want to publish to a production Web server. Configure the Debug configuration to be in Master mode, and configure it with the appropriate settings to publish files to your testing Web server. Each time you save a file locally, it’ll be published to your testing server immediately. Keep the Release configuration in Local mode, and switch to Release mode when you’re ready to publish all changed files to your production Web server.

Project Publishing Once you’ve defined transfer destinations (in the project’s configurations), you can publish your project. On the Build toolbar, select either Debug or Release to control where your project is published. Then, right-click the project in the Workspace Browser (or open the Publish menu) and select Publish All to publish all project files, or Publish Changes Only to publish only files which have changed since the last publishing operation.

If you want to publish to multiple destinations at once, see Multi- Target Publishing later in this chapter.

66 Backing up a Project Backing up your project all at once is simple: Click the Backup button on the build toolbar, select Backup project files from the Project menu.

Running a Project To run a project, click the Run button on the Build toolbar, or select Run active project from the Project menu.

Multi-Target Publishing PrimalScript Enterprise includes multi-target publishing capabilities. This allows a project to be published to multiple targets at the same time, such as publishing a Web project to multiple servers in a Web farm. Multi-target publishing is only available in PrimalScript Enterprise

In order to use the multi-target publisher, a project must be open in PrimalScript (you cannot publish individual files to multiple targets; only files which are part of a project can be published to multiple targets). To start the multi-target publisher, select Publish to multiple targets from the Project menu.

Multi-Target Publisher

To operate the multi-target publisher: • Click Publish to publish the current project to all listed targets. • Click Close to close the multi-target publisher • Click Load Profile to load a previously-saved list of targets • Click Save Profile to save the current list of targets • Click Add Target to add a new target. You must do this before you can configure the properties for a target. • Click Remove to remove a target from the list. After adding a target, you can specify its name. This name appears only in the list and has no relationship to the target’s server name or other information. For each target, configure: • Protocol. Select FTP or Network Copy. • Host. This is the target’s server name. Do not include “\\” or other characters when using network copy, and do not include ftp:// when using FTP.

68 • Path. The path where the project should be copied. For a network copy, specify “share\path\path” without any leading backslash; for FTP, enter the path from the FTP root, and do not specify any leading slash. • User ID and Password. Available only for FTP operations. For network copy, your current logon credentials must have sufficient rights on the destination (or, manually execute a NET USE command from the command-line to specify alternate credentials). • Options. Select any of the four options, as appropriate. These options are configured per-target, not for the entire multi-target publishing process.

To publish to a mapped drive, enter the complete drive letter and path (such as “M:\MyFolder”) in the Path field, and leave the Host field blank.

69 Chapter 7: Advanced Features and Customization

Customizing PrimalScript Toolbars and Shortcut Keys PrimalScript offers a number of different customization options, allowing you to tweak the environment to meet your specific needs and preferences. Shortcut keys and toolbars are customized by selecting Customize from the Tools menu.

Customize dialog

70 Customizing Keyboard Shortcuts To customize shortcut keys, simply select the menu option or operation that you want to customize. Currently-assigned keyboard shortcuts are listed, and you can remove them as desired. You can also create a new shortcut key by clicking on “None” (in the text box) and pressing the desired shortcut combination.

Customizing Toolbars Customizing toolbars allows you to indicate which toolbars you want displayed. You can also access this functionality simply by right-clicking an existing toolbar, and then selecting or de- selecting the toolbars you want shown or hidden. In addition, you can create custom toolbars, and place whatever buttons on them that you want. You can also customize the buttons on the built-in toolbars. To do so, select the Commands tab in the Customize dialog, and simply drag the desired commands from the dialog onto the desired toolbar.

Customizing the Mouse, Menu, and other Options You can also customize menu options, mouse behavior, and toolbar options from the Customize dialog.

Customizing PrimalScript Options PrimalScript has a vast array of customization options available by selecting Options from the Tools menu. Each major options category will be explained here. • Environment o Languages This section allows you to customize how each language recognized by PrimalScript is implemented. You can specify the executable used to compile, debug, or execute scripts, as well as options for prompting for arguments, capturing output to the Output tab, and so forth.

Language options o File Groups This section allows you to define and edit the file type groups used by PrimalScript. You can use the Associate button to associate PrimalScript with the selected file type, so that PrimalScript becomes the file type’s default application. o Print This section allows you to customize PrimalScript’s printing features by specifying page headers and footers, alignment, printed line numbering, and so forth. o Directories This section allows you to define the default folders for various PrimalScript elements, including Snippets, templates, the Info Browser, the “My Scripts” folder, the macros folder, the default folder for new projects, and the ActionScript class path.

72 It is recommended that you leave most of the directories at their defaults. If you do change them, be sure to duplicate the default subdirectory structure. For example, the “Templates” folder is expected to contain several subfolders, which provide key functionality. The “My Scripts” and “Projects” directories are the only ones you can freely change to another folder, if desired.

o Help This section customizes PrimalScript Universal Help. Chapter 9 discusses these options in more detail. o Browser Windows This section allows you to customize the Browser windows. Chapter 5 provides more detail on using these options. o Document Tabs This section customizes the display, position, sort order, and appearance of document tabs within the PrimalScript code window. o Backup This section allows you to specify options for file backups. You can have backups automatically created when saving a file, when moving out of PrimalScript to another application, and automatically on a set schedule. • Source Control This section, discussed in more detail in Chapter 8, configures PrimalScript source control integration. • Text Editor

73 o General This section provides options for various text editor functions, including specifying the “skin” used to display various portions of the PrimalScript user interface.

One option in particular you should know about is “Check for changed remote files.” Normally, PrimalScript monitors all files that you’re editing to see if they’re modified by another application. If they are, PrimalScript will warn you and offer to re-load the new version of the file into the editor window. By default, this behavior is disabled for files stored on a mapped network drive or UNC; some networks experience problems that result in false alerts within PrimalScript. You can enable the check behavior for network files by selecting the “Check for changed remote files” checkbox.

Text editor general options o Colors This section allows you to customize 74 PrimalSense code coloring. You can specify a unique foreground/background color for each language element that PrimalScript recognizes. o Macro Keys This section allows you to assign shortcut keys to macros that you have recorded. Macros are discussed later in this chapter. o PrimalSense These options control PrimalSense behavior, including enabling or disabling various PrimalSense features. When working with HTML and DHTML, you may want to enable the Show Browser and Server objects in JScript and VBScript files to enable PrimalSense for intrinsic browser and server objects. o Type Libraries This allows you to specify the type library files (.tlb files) associated with specific COM progIDs. If you find that PrimalSense isn’t working for a particular progID, locate the component’s TLB file and specify it in this section, so that PrimalSense can locate the TLB and use it to provide code hinting and completion. • Debugging This option allows you to enable Windows Socket Debug Messages, and to specify a port for these messages. This is an advanced feature typically used only by programmers working with C++ and Windows APIs. • Windows Script Host This section allows you to configure a number of WSH-related options. You can select WScript or CScript to be used to run scripts from within PrimalScript, and if you select CScript you can have the option (enabled by default) to have PrimalScript

75 capture your script’s output on an Output tab. You can also specify a certificate and security settings; these are discussed in more detail in Chapter 10.

Comparing Files with PrimalDiff™ PrimalDiff™ is only available in PrimalScript Professional and PrimalScript Enterprise

PrimalDiff is used to compare two files to one another and visually explore their differences. To start PrimalDiff, select Compare two files from the Tools menu (PrimalDiff is also used when comparing file versions through source control integration). Specify the two files to compare (use the two … buttons to browse for files), and then click OK.

Compare files dialog

Lines of code which differ between the two files are highlighted in gray. Lines in blue, with a (*) indicator, are different. Lines in red, with a (-), are present in one file, but missing in the other. The two panes are scroll-synchronized: Scrolling either pane also scrolls the other one automatically, so that you can more easily compare the two files’ contents.

Checking Spelling PrimalScript includes a spell-check feature, which is particularly useful in text or HTML documents (although the spell checker does not, by default, recognize many tag and attribute names in HTML documents; to check a block of regular text, simply select the text before beginning). Simply select Check Spelling from the Tools menu to activate the spell-check process. 76 The spell-check feature works similarly to spell-check in Microsoft Office, including support for multiple dictionaries, the ability to add words to a custom dictionary, and so forth.

Sending and Receiving Files via FTP All editions of PrimalScript include basic FTP capabilities. However, PrimalScript Professional and PrimalScript Enterprise also include a full-featured, built-in graphical FTP client. Read more about it in Chapter 12.

PrimalScript includes basic built-in FTP functionality to make sending and receiving files easier. To use this functionality, select Get or Put from the File > FTP menu. If you select Put, you’ll first be prompted to select a local file. Either way, you’ll then be presented with the Get or Put dialog. Specify the file to get (or put), the FTP site address (which is entered in the Look in combo box), and, if necessary, your login credentials (which defaults to Anonymous) Click OK to begin the FTP operation.

Miscellaneous Tools The Tools menu offers access to a number of handy tools: • Program. Launches an external program you specify. • Command Shell. Launches a command-line window. • Clipboard. Launches the Clipboard Viewer.

77 Chapter 8: Source Control Integration

Setting up SourceSafe-Compatible Source Control Before configuring PrimalScript for source control, you must install your source control software’s client.

Your source control software must either be Microsoft Visual SourceSafe, or your source control provider must provide an SSAPI-compatible client, which you must install and configure according to the manufacturer’s instructions.

To configure source control integration, select Options from the Tools menu, and select Source Control. Check the Enable Source Control connection checkbox (or click the corresponding button on the View toolbar) to enable source control. Note that your source control provider must be displayed in the Provider list; if it is not, then source control is not properly installed and will not be available to PrimalScript.

78 After enabling source control, you can configure the options however you like, including prompting before checking files out and automatic check-in options.

Setting up CVS-Compatible Source Control PrimalScript can also work with CVS-compatible source control solutions. To begin, you’ll need the CVS client software installed on your computer. You also need to know that every CVS repository has a root, and you need to know the path to that root. This may be specified as an HTTP URL, as a UNC path, or just a local file path. In any event, you’ll need the appropriate permissions and passwords in order to successfully set up PrimalScript. For example, if the CVS root is a local path, then it might be C:\CVS, and PrimalScript would expect the folder file:///C:/CVS/CVSROOT to automatically exist. Open PrimalScript, select Options from the Tools menu, and select the Source Control section. Select the Enable CVS connection checkbox, and under CVS Server Path enter the path.

Whatever path you specify; PrimalScript will look for the CVSROOT subfolder underneath it. Do not specify the CVSROOT subfolder as part of the path you enter into the Options dialog!

A network path might be entered as file:///Server/CVS, and PrimalScript would expect \\Server\CVS\CVSROOT to already exist. If you need to provide a password to access this share, then that password must already be in your system’s cache. For example, you should try to manually open the share using Windows Explorer; when prompted for a password, select the option to have the password remembered by Windows.

79 PrimalScript is not able to prompt for passwords, should they be required. You need to ensure that Windows is able to access the CVS path without displaying a password prompt.

An HTTP path might be something like http://intranetserver:2121, where 2121 is the port. Any required username and password can be specified in this URL, as well; you should review the CVS documentation for information on doing so. Note that your locally-installed source control client software must be able to handle WebDAV and authentication, and this information must be cached.

Using Source Control Before a script can be managed through source control, it must first be added. To do so, simply open the script and click the Add button on the Source Control toolbar (or select Add to source control from the Tools > Source Control menu).

You must first save unsaved scripts before they can be added. If you do not, PrimalScript will prompt you to save the file first.

Your source control software governs the add process, and may prompt you for login credentials, a location for the script, and other information. Once added, scripts can be checked in or out using the Source Control toolbar, or the Tools > Source Control menu. Some notes about working with source control: • Get Latest Version retrieves a read-only copy of a file.

80 • Remove from Source Control does not automatically delete any local copies of the file. • Select Source Control… from the Tools > Source Control menu to launch your source control software’s user interface. • Select Connect folder… from the Tools > Source Control menu to connect a local folder to a source control project. This makes it easier to work with groups of files, since they can be more easily checked in and out as a unit, and since they’ll be conveniently located in a single local folder on your computer when you’re working with them. It’s important to realize that PrimalScript does not provide source control capability; it simply integrates with the features of your compatible source control software. For that reason, some features described here may not be available in your software, or might work somewhat differently.

Using CVS with PrimalScript There are a few notes you should be aware of that govern how PrimalScript works when connected to a CVS-compatible source control solution. • All PrimalScript projects are created directly under the CVS root—any projects added to CVS source control will be added as root objects. • In PrimalScript, using the “Check In” functionality is equivalent to “Update/Commit” in CVS; the PrimalScript “Check Out” functionality is the same as a CVS “get.” • You can read more about CVS and WebDAV (which allows CVS to be accessed through an HTTP URL) at http://ximbiot.com/cvs/cvshome/cyclic/cvs/dev- dav.html. • You can download CVSNT—the version of CVS for Windows—at http://www.march-hare.com/cvspro/

81 Troubleshooting If you’ve configured source control integration but it doesn’t seem to be working, ensure that your source control password contains only letters and numbers. Remove any punctuation or spaces, as these sometimes cause integration problems (this has been especially noted with Borland StarTeam).

82 Chapter 9: Universal Help

PrimalScript provides truly universal, integrated help for most scripting languages, providing you with access to the manufacturer’s documentation and with context-sensitive help. If you install the manufacturer’s language documentation before PrimalScript, PrimalScript will in many cases be able to automatically configure itself to use the documentation. However, in some cases you will still need to manually configure PrimalScript to provide full help capabilities. To do so, select Options from the Tools menu. Under Environment, select Help.

Help options

The complete list of supported languages is listed in the middle; to the right are language-specific settings. These settings can be set independently for each supported language. PrimalScript supports three different kinds of help: • Context-sensitive help files. Generally supplied in HLP or CHM files. To use one, simply provide the complete path to the file or files. • HTML-based help. Simply provide the folder containing the help files. • Internet-based help. Simply provide the URL of the Internet-based help search engine. You can also provide a URL such as www.google.com/search?q=$Keyword$, which will search the Google search engine. When typing the URL, use $Keyword$ where the URL expects the search keyword to be. When properly configured, PrimalScript help is context sensitive. In other words, if you open an ActionScript document and select a keyword, and then press F1, Macromedia’s HTML help should appear and display assistance for that keyword.

84 PrimalScript Help is language- sensitive. If you’re editing a JScript document and haven’t configured Help settings for the JScript language, then pressing F1 may not do anything, even though you may have configured Help for the similar JavaScript language—which PrimalScript treats as a distinct, independent language.

MSDN Library Integration In addition, PrimalScript can integrate with Microsoft MSDN Library—either the current edition, or the pre-Visual Studio .NET edition issued before January 2002. Simply select the appropriate setting (this is obviously most useful for Microsoft languages like VBScript, VB.NET, and so forth). You can also select a search filter, which will be passed to MSDN Library.

The proper edition of MSDN Library must be installed on your computer in order for MSDN Library integration to function. You can download MSDN Library for free from Microsoft’s Downloads Web site.

When properly configured, PrimalScript help is context sensitive. In other words, if you open a VBScript document and select the word InputBox, and then press F1, MSDN Library (or the VBScript documentation, depending on what you’ve configured), should display assistance for that function.

85 Special Help Features PrimalScript provides special integrated help capabilities for VBScript and Windows PowerShell, which are enabled by default. In either language, moving your cursor to a keyword and pressing F1 will display help. • For Windows PowerShell, help is drawn directly from the shell itself. Help is only available for cmdlets for which an XML help file is provided; third-party snap- ins may not include help, in which case PrimalScript cannot display it. • For VBScript, help is provided as an electronic edition of WSH and VBScript Core: TFM by Jeffery Hicks. Keyword help is extracted from the text and displayed in PrimalScript’s Help pane.

86 Chapter 10: Windows Script Host and Windows PowerShell Features

PrimalScript provides a number of features designed to make Windows Script Host (WSH) scripting—in VBScript and JScript, primarily—easier and more efficient, as well as features designed exclusively for working with Windows PowerShell.

Windows Script Files A Windows Script File (.wsf filename extension) is a special, XML-formatted file that can contain multiple scripts (referred to as jobs), define command-line arguments, and more. Using the WSF format, you can essentially write your own command-line tools using VBScript or JScript. Although the XML format is complex, you don’t need to worry about it, because PrimalScript handles it all behind the scenes, allowing you to focus on your scripts.

Starting a WSF A WSF is a special kind of PrimalScript project. To begin one, select New > Project from the File menu. Under Windows Script Host Projects, select Windows Script File. Provide a name and location for your new file, and specify a name for the workspace. Next, specify the basic properties: The name of the script, the location where it will be stored, the name of the first job in the WSF, and the scripting language. 87 Next, select any objects that will be used within the job. You can click Browse to add objects which aren’t on the default list. By referencing the objects that your scripts will use, you can use any constants defined in the objects’ type libraries. Similarly, you can add various other references on the next screen. Finally, you can add additional files to the job. These can be automatically copied to the script folder if desired. After completing the Wizard, your new WSF will be ready. You can begin managing it by using the Workspace Browser.

WSF Workspace The WSF is part of a special PrimalScript workspace. You can add additional scripts, or jobs, to the workspace. To do so, right- click the top-level workspace item in the Workspace Browser and select Add new job to workspace. The context menu also offers options to add the workspace to source control (or, if it’s already been added, check it in or out).

Workspace context menu

You can also open the workspace (that is, the WSF file) as a text file. Doing so provides access to the raw XML formatting as well as the script code of the jobs contained in the workspace.

Viewing a WSF as a text file

The Workspace Browser provides the key to managing the file. In addition to the actions available by right-clicking the top-level workspace item, you can also right-click a job (the next level of item), or any of the items within a job.

Workspace Browser

Right-clicking a job (such as “MultiComputer,” shown here) gives you options to: • Run the job • Debug the job • Set the job as the active job 89 • Remove the job • Add files to the job • Add scripts to the job • Add references to the job • Add objects to the job • Add resources to the job Right-clicking other objects—such as objects, references, or scripts—allows you to remove or rename them, as appropriate.

Remember, each WSF file, or workspace, can contain multiple jobs. Each job can contain one or more scripts, files, references, objects, and so forth. To execute the final WSF and run a specific job, run filename.wsf //job:jobid.

WSF Properties Each job within a WSF workspace has a set of properties. These include the job’s name (or ID), which is used to reference the job when running the final WSF. The job can also have a text description, which describes what the job does. If the WSF is run with only a /? argument, the description is part of what is automatically displayed. A job can also have a usage explanation, and an example. Both are textual fields that embed information within the job for future reference. Finally, jobs can have zero or more arguments. These are defined command-line arguments, which can be accessed within the job’s scripts via the WScript.Arguments object. Arguments have a description, or name. For example, the argument shown here would be accessed from the command line like this: multicomputer.wsg /list:listname, using the argument’s name. Arguments can also have a line of help text,

90 which is displayed as part of the automatic /? feature. Finally, arguments have a type. The type can be string, Boolean (meaning True or False) or simple. Simple arguments are simply specified or not; they are not given a value. For example, /verbose is an example of a simple argument: Either it’s specified, or it isn’t.

WSF Code Script code is included within the WSF normally, using the PrimalScript code window. PrimalScript handles the XML formatting necessary to enclose the script within its job, and the job within the overall WSF.

Script code within a WSF

Windows Script Components A Windows Script Component (.wsc filename extension) is a special, XML-formatted file that allows a script to function as a COM object, much like a DLL. Using the WSC format, you can essentially write your own modular COM components using VBScript or JScript. Although the XML format is complex, you don’t need to worry about it, because PrimalScript handles it all behind the scenes, allowing you to focus on your scripts. 91 Starting a WSC A WSC is a special kind of PrimalScript project. To begin one, select New > Project from the File menu. Under Windows Script Host Projects, select Windows Script Component. Provide a name and location for your new file, and specify a name for the workspace. Next, specify the basic properties: The name of the script, the location where it will be stored, the ProgID which will be used to reference the component, and the scripting language. Next, select any objects that will be used within the component. You can click Browse to add objects which aren’t on the default list. By referencing the objects that your scripts will use, you can use any constants defined in the objects’ type libraries. Similarly, you can add various other references on the next screen. Finally, you can add additional files to the component. These can be automatically copied to the script folder if desired. After completing the Wizard, your new WSC will be ready. You can begin managing it by using the Workspace Browser.

WSC Workspace The WSF is part of a special PrimalScript workspace. You can add additional components and their scripts to the workspace. To do so, right-click the top-level workspace item in the Workspace Browser and select Add new component to workspace. The context menu also offers options to add the workspace to source control (or, if it’s already been added, check it in or out). You can also open the workspace (that is, the WSC file) as a text file. Doing so provides access to the raw XML formatting as well as the script code of the jobs contained in the workspace.

Viewing a WSC as a text file

The Workspace Browser provides the key to managing the file. In addition to the actions available by right-clicking the top-level workspace item, you can also right-click a component (the next level of item), or any of the items within a job. Right-clicking a component (such as “Windows Script Component,” shown here) gives you options to: • Register the component • Unregister the component • Generate a type library for the component • Remove the component • Add files to the component • Add scripts to the component • Add references to the component • Add objects to the component • Add resources to the component

93 • Modify the component’s properties Modifying the component’s properties allows you to change its ProgID, description, and other details. Right-clicking other objects—such as objects, references, or scripts—allows you to remove or rename them, as appropriate.

Remember, each WSC file, or workspace, can contain multiple components. Each component can contain one or more scripts, files, references, objects, and so forth.

WSF Code Script code is included within the WSC normally, using the PrimalScript code window. PrimalScript handles the XML formatting necessary to enclose the script within its job, and the job within the overall WSC.

WSC Properties, Methods, and Events Just as with regular COM components, a WSC can have members—properties, methods, and events. These are added by right-clicking the Interface item in the Workspace Browser and selecting the appropriate menu item. When adding a method, you’ll specify its name and any parameters it will accept. PrimalScript will create the necessary function shell to implement the method. Similarly, creating a property allows you to indicate if it is a read/write property, a read-only property, or a write-only property, and PrimalScript creates the appropriate routines to handle the getting (reading) and setting (writing) of the property. Note that members can have different external names (the names used when programming with the component from within another script) and internal names (the name the member is known by within its own script).

Shell functions for a read/write property

Using a WSC Before a WSC can be used, it must be registered, just like a COM DLL. To do so, simply select Register active component from the Script menu, click the Register Component button on the Script toolbar, or right-click the component in the Workspace Browser and select Register Component. The component can be unregistered in the same way. You can also generate a type library (.tlb file) for the component, which allows features like PrimalSense to function for the component’s members.

Windows PowerShell Snap-Ins PrimalScript hosts the default Windows PowerShell instance; it does not host specialized shell instances such as the Exchange Management Shell (EMS). However, PrimalScript can work with the snap-ins from these specialized shells. You must create a Windows PowerShell profile: • Create the folder. Your profile folder goes in your “My Documents” or “Documents” folder, and is named “WindowsPowerShell.” • Create the file. Your profile file must be named “Microsoft.PowerShell_profile.ps1” and it must be in the folder specified above. • Load snap-ins. In your profile, add Add-PSSnapIn commands to load whatever snap-ins (such as the

95 EMS snap-in, PowerShell Community Extensions, etc.) you want to work with. Once your profile is properly configured, open PrimalScript and create a new Windows PowerShell script file. You should be able to see PrimalSense features working for the cmdlets that are defined in the snap-ins you added, including context-sensitive help (assuming help is provided with the snap-ins).

Script Signing PrimalScript includes the ability to digitally sign VBScript, JScript, WSF, and Windows PowerShell scripts, provided you have installed a valid code-signing certificate on your computer. The certificate should be installed to the default personal store. First, you need to configure PrimalScript with the name of the certificate. Do so by selecting Options from the Tools menu, and then selecting Script Settings and then Script Security. Enter the name of the certificate and leave the Store textbox blank, to use the default store. You can elect to have PrimalScript automatically sign all scripts when those scripts are saved. Note that different certificate settings are available for Windows PowerShell and Windows Script Host (VBScript and JScript). Otherwise, you can manually sign scripts, either by selecting Sign Script from the Script menu, or clicking the Sign Script button in the Script toolbar.

Windows Script Host TrustPolicy Settings PrimalScript includes support for Windows Script Host TrustPolicy, which is a feature built into WSH that can help prevent untrusted scripts from running. PrimalScript provides access to the per-user TrustPolicy configuration through the Options dialog.

96 On Windows XP and later computers, you must first manually set the registry key HKEY_CURRENT_USER\SOFT WARE\Microsoft\Windows Script Host\Settings\UseWINSAFER to 0 in order for TrustPolicy to take effect. Doing so allows TrustPolicy to override Software Restriction Policies.

Be aware that TrustPolicy can also be configured on a machine- wide basis in a way that overrides the settings PrimalScript configures, and that these settings can be deployed in a non- overridable fashion from Group Policy.

Script Encoding PrimalScript can save VBScript and JScript scripts that are encoded using the Windows Script Encoder. The Encoder helps to protect the source code of your script while still allowing WSH to execute it. However, because numerous Decoders exist on the Internet, you should not rely in Encoding to protect sensitive information, such as credentials, that are hardcoded into your scripts. To encode a script, select Save script encoded from the Script menu.

WMI Wizard PrimalScript includes a convenient WMI Wizard that writes short Windows Management Instrumentation scripts for you. Activate the Wizard by selecting WMI Wizard from the Script > Wizards menu, or by selecting WMI Wizard from the Wizards button on the Script toolbar.

97 The Wizard can query most available WMI classes. By default, it looks only at classes beginning with “Win32,” in the root\cimv2 namespace of your local computer.

WMI Wizard dialog

The Wizard can produce scripts in either VBScript or JScript, although it defaults to the language currently in use, if you open it while a VBScript or JScript file is open and active. To query the WMI namespaces on another computer, specify that computer’s name in place of “.” and, if necessary, provide proper credentials for the remote computer. To display classes other than those in the \root\cimv2 namespace, type the new namespace (such as \root\MicrosoftIISv2). Finally, uncheck the Show only WIN32 classes checkbox to display classes whose names do not begin with “Win32.” After specifying these options, click Refresh to refresh the class list. Select any class to see its sample script, and click Insert to insert the script into your current file, or click Copy to copy the WMI script to the Clipboard.

98 ADSI Wizard The ADSI Wizard is only included in PrimalScript Professional and PrimalScript Enterprise.

PrimalScript includes a convenient ADSI Wizard that makes writing Active Directory Services Interface scripts easier for you. Activate the Wizard by selecting ADSI Wizard from the Script > Wizards menu, or by selecting ADSI Wizard from the Wizards button on the Script toolbar.

The ADSI Wizard only produces code in VBScript.

Tell the Wizard which ADSI objects you want to work with: Users, Contacts, Computers, Organizational Units, or Groups. For each type of object, you can have the Wizard produce sample code showing how to add, delete, or modify objects.

ADSI Wizard dialog

The Wizard creates a new class for each type of object selected, as well as a generic ADSIConnection class which connects to ADSI. The code added by the Wizard is pre-folded.

Additional sample code demonstrates how to use the new classes to query and work with ADSI objects.

• To begin: Declare a variable which will represent a retrieved ADSI object. Set the variable equal to a new instance of the appropriate class (e.g., Set objUser = New ADSIUser) • To retrieve an object: Use the appropriate method of objADSI. The first argument of the “Get” method (such as GetUser) should be an object variable that will represent the retrieved object. • To work with an object: Use the methods of the newly-retrieved object. To assist you, the classes added by the ADSI Wizard all support PrimalSense. For example, the objADSI variable supports methods for dealing with all of the object types you selected in the Wizard.

100

Pop-up tool tips help remind you of the correct syntax for using each class.

The objects will also display PrimalSense code hinting to help you select the appropriate property or method. Rather than attempting to write scripts for you, the ADSI Wizard creates code that makes ADSI scripting easier, by providing objects which represent specific classes, including full PrimalSense support, and makes ADSI scripting more intuitive and direct.

ADO Wizard The ADO (ActiveX Data Objects) Wizard is accessible from the Database Browser. Please refer to the Database Browser for details.

Compiling (Packaging) Scripts Script “Compiling” for some languages, including VBScript, is only included in PrimalScript Professional and PrimalScript Enterprise.

Compiling (Packaging) a script creates a standalone executable, having the same name as the script. This standalone executable can be deployed to any computer that already has the appropriate scripting technology (Windows Script Host, for example) installed. 101 To compile a script, click the Compile/Syntax Check button on the Script toolbar, press Ctrl+F7, or select Compile/Syntax Check on the Script menu. The executable will be created in the same folder as the original script. For additional options, including the ability to bundle several scripts into a single executable, specify a custom executable icon, and more, please refer to Chapter 13.

In languages such as VBScript, the “Compile” option is merely a shortcut to the ESP™ functionality. Refer to Chapter 13 for more details.

102 Chapter 11: Script Debugging

PrimalScript provides access to both external debuggers and, for Windows scripts (VBScript and JScript), a built-in, highly functional PrimalScope™ debugger.

Using External Debuggers External debuggers can be specified on a per-language basis, using the Options dialog.

Language options

103 To begin debugging a script in an external editor, click the Debug Script button on the Script toolbar, press Shift+F7, or select Debug Script from the Script menu. External debuggers, such as the Microsoft Script Debugger, differ in functionality and operation. Please consult the debugger’s documentation for information on operating it.

Using the PrimalScope™ Windows Script Debugger The PrimalScope™ Windows Script Debugger is only included in PrimalScript Professional and PrimalScript Enterprise

PrimalScope provides built-in, highly functional debugging for Windows VBScript (VBS) and JScript (JS) files.

Installation and Security

The information in this section is very important to understanding how PrimalScope works, and what its limitations and requirements are.

PrimalScope relies on certain Microsoft Windows components, including the Machine Debug Manager and Process Debugger. These are already available on most Microsoft Windows computers, although they may not be properly registered with the operating system. In addition, PrimalScope is designed to obey Windows’ security infrastructure regarding debugging. As a result, the following conditions apply to PrimalScope’s use: • PrimalScope may need to be used, for the first time on a given computer, by a user who has permissions to install and start new services (specifically, the Microsoft Machine Debug Manager, which may already exist but which may need to be registered and started). You can see if this will be necessary by 104 examining the list of services installed on the computer; if the Machine Debug Manager service exists and is started, PrimalScope will not need to register it and start it. • PrimalScope can only be used by user accounts possessing the Debug Windows user right. This is by design and cannot be circumvented. • If PrimalScope is unable to access the Machine Debug Manager service, or if it is unable to obtain Debug permissions from the operating system, it will display an error message. • Some Microsoft software may create a “debugging” or “debugging-users” group. The user running PrimalScript needs to belong to this group in order for PrimalScope to work properly. Please note that some organizations “lock down” their computers using Group Policy objects, user rights assignment, and security templates. If your organization has done so in such a way that your user account is unable to properly register or start the Machine Debug Manager service, or if your user account does not have the Debug user right, then PrimalScope will not function. PrimalScope’s inability to function is a consequence of the security decisions your organization has made, and SAPIEN Technologies cannot provide a workaround for your organization’s security policies. These conditions are imposed because PrimalScope uses many of Windows’ own services and capabilities to provide advanced debugging features, and those services and capabilities are integrated with Windows’ own security infrastructure.

Working with Breakpoints Breakpoints instruct the debugger to stop on a specified line of code. This allows you time to review what the script is doing at that point. To set a breakpoint, place your cursor on the desired line and either press F12, select Toggle Breakpoint from the Debug menu, or click the Toggle Breakpoint button on the Debug toolbar.

105

Debug toolbar

Repeating this step on the same line will remove the breakpoint. You can remove all breakpoints by selecting the adjacent button on the toolbar, or by pressing Ctrl+Shift+F12. Set breakpoints are indicated by a red circle in the margin of the code window.

Breakpoint indicator

Debugging Scripts To begin debugging a script, press Ctrl+Alt+F5, select Go from the Debug menu, or click the Debug Script button on the Debug toolbar (do not confuse this with the similar-appearing button on the Script toolbar).

Debug toolbar

The script will run normally, with output captured to the Output tab, until a breakpoint is reached. A yellow arrow in the margin of the code window indicates the next line of code that will execute.

Next line of code indicator

106 Press F11 to execute the indicated line of code and stop again. Notice that the yellow arrow advances to the next line of code. In this fashion, you can watch your script execute one line at a time. To stop debugging, press the Stop debugging button on the Debug toolbar, press Shift+F5, or select Stop Debugging from the Debug menu. Note that when your script is paused due to a breakpoint, you can add or remove breakpoints, but you cannot edit the script.

Adding Arguments You may write scripts which are intended to be run with command-line arguments. In order to test these scripts under PrimalScope, you need to be able to pass test arguments into your script. Do so by selecting Set Arguments from the Debug menu. This feature will allow you to specify script command-line arguments while debugging.

Examining Variables and Object Properties A pane near the bottom-left of the PrimalScript window provides a hierarchical view of both variable values as well as object property values. Only objects and variables defined thus far in the script are displayed.

Examining variable and object property values

This display is updated each time a line of script code is executed, allowing you to easily examine the contents of object properties and variables, so that you can see what information your script is working with. Note that, for performance reasons, PrimalScope does not query object properties by default. To enable this feature, open the

107 Options dialog from the Tools menu, and select the Debugging>General section.

Configuring debugging options

Here, you can enable the querying of object properties and specify the maximum number of nested properties (in an object hierarchy) that PrimalScope will attempt to query. Larger query levels may result in poor performance or, with some complex objects, a debugger hang.

Evaluating Expressions PrimalScope can evaluate complex expressions to help you see what results your script is coming up with. To evaluate an expression while the script is paused, highlight the expression in the code window.

Highlighting an expression

108 Then, drag the expression to the Expression Watch pane at the bottom-right portion of the PrimalScript window. The expression is immediately evaluated so that you can see its result. The expression will be re-evaluated each time a line of script is executed, so that you can continually view the expression’s result.

Evaluating expressions at run-time

Any number of expressions can be added to the list. To remove an expression, select it in the list and press Delete.

109 Chapter 12: Built-in FTP Client

The built-in FTP Client is only available in PrimalScript Professional and PrimalScript Enterprise

PrimalScript (Professional and Enterprise) includes a full- featured, built-in FTP client that makes working with remote files and folders easier. To open an existing FTP connection, simply select the connection name from the drop-down list on the FTP Toolbar. Or, open the FTP Sites dialog: • Click the FTP Properties button on the FTP toolbar

FTP Sites dialog

• Select Explore FTP Sites from the Tools menu Once the dialog is displayed, select an FTP site and click Connect, or click New Site to define a new FTP site. When 110 defining an FTP site, you can specify an alternate port, provide login credentials, specify a starting folder, and even specify a local folder. That local folder will be displayed in the File Browser, providing quick and convenient access to those files. The remote (FTP) folder opens in a new tab in the main window; local files are accessible in the File Browser, to the left. Files can be dragged between the local and remote folders; buttons on the FTP toolbar allow you to navigate up a folder on the remote server, create new folders, and switch between icon- and list-style views of the remote files and folders.

Although the FTP client is only available in PrimalScript Professional and PrimalScript Enterprise, basic FTP capabilities are available in all editions of PrimalScript. These are described in Chapter 7.

111 Chapter 13: Packaging Scripts using the Evolved Script Packager™

The Evolved Script Packager™ is only available in PrimalScript Professional and PrimalScript Enterprise

You can quickly compile an open script into an executable by using the Compile/Check Syntax button on the Script toolbar, although you cannot specify advanced options like alternate credentials. See Chapter 10 for more details.

ESP provides the ability to package multiple scripts, supporting files, and even COM components into a single, standalone executable. To begin packaging, click the Script Packager button on the Script toolbar. Or select, Script Packager from the Script menu. The Script Packager dialog contains everything you need to create your package.

112 The packager allows you to enter alternate credentials, which will be used to execute the scripts in the package. However, the user actually running the packaged executable must have the necessary user rights within Windows in order to activate the alternate credentials. Typically, users do have these permissions, also allowing them to use the Windows Runas command-line utility.

Applicability The Evolved Script Packager can package scripts of the following types: • VBScript (VBS files) • JScript (JS files) • Windows PowerShell (PS1 files) • HTML Applications (HTA files) A single package, however, can only contain script files from one of these categories.

113 General Settings

• Click New to begin building a new package, or click Load to load a previously-saved package. • Output file is the path and filename of the final executable. • Optionally, you can specify a custom icon (.ico file format) for the final executable. • Select the appropriate Execute with option for the types of scripts you plan to include in the package: o WScript and CScript can run VBS and JS files. They write the script as a temporary file, which is removed after the package completes. o SAPIEN Script Host can run VBS and JS files. It executes entirely in-memory and does not use temporary files. The SAPIEN Script Host is included in the package and does not need to be deployed in advance. o Windows PowerShell can run PS1 files. It must be deployed in advanced wherever the package will run. o MSHTA runs HTA files. • Select Delete data files after script(s) execute to have unpackaged data files removed after the 114 package’s script or scripts finish running. If this checkbox is cleared, unpackaged data files will be left in place.

Folders • The Target folder option indicates where the script and data files will be unpackaged during execution. You have three options: o Temporary folder. This will write the scripts to C:\Temp, a folder which will be created if it does not exist. o Current folder of executable file. This will write the scripts to the same folder as the package executable. o Specific folder. This allows you to specify the folder where the scripts will be written.

The user running the package must have Read and Write permissions to whatever folder you designate. The alternate credentials you can supply in the package (see below) are not used to write the script files; if the user running the package doesn’t have the necessary permissions, then the package will display an error and fail to execute properly.

• The COM folder path indicates where COM objects will be unpackaged during execution. This is an optional path, and you can specify it if you need to have your COM object files located in a fixed place. The user running the package must have permission to write files to this folder. The user running the

115 package must also have permission to register new COM objects on the local computer.

Security Settings By default, the scripts in the package will execute under the security context of the user that runs the package. However, you can specify alternate credentials (a user name and password), which will be used to run all scripts within the package.

If you need to specify a specific domain, use the username@domainname format, not the older domain\user format. Do not specify a domain or computername for local accounts.

The alternate credentials you supply must be available (either as local or domain accounts) on any computer where the compiled package will run. In addition, the credentials must generally have local administrator privileges on the computer where the compiled package will run.

Additionally, packaged scripts that specify alternate credentials are only supported on Windows 2000 and later. Prior versions of Windows, including Windows 95, Windows 98, and Windows Me, lack the necessary security features to safely implement packaged alternate credentials. You can also select the Encode scripts checkbox to encode scripts within the package, helping to protect your source code. You can also select the Sign scripts checkbox to automatically add a digital signature to all scripts before packaging. You should sign the scripts if your organization implements WSH TrustPolicy. In order for script signing to work, you must already have configured PrimalScript with the name of a code-signing certificate; read Chapter 10 for more information on script signing.

116 Files Packages can contain scripts, data files (which can be any file type you want to add), and COM objects (which are usually DLL files). To add a file, select the Script Files, Data Files, or COM Objects folder and click the Add button. Move files up and down using the Move up and Move Down buttons; keep in mind that scripts will execute in the order shown. To remove a file, select it in the list and click the Remove button. COM objects included in a package will be automatically registered, if necessary, when the package is executed. This make the package a convenient way to deploy these objects along with the scripts that use them. However, in order to take advantage of this functionality, COM objects must be self- registering. You can test this capability by opening a command- line window and running Regsvr32 objectname.dll, providing the appropriate COM object filename. If you receive a “success” message, then the object is capable of self-registration.

117 Chapter 14: The Remote Script Execution Engine™

The Remote Script Execution Engine™ (RSEE™) is an enterprise-level remote script execution environment. It consists of two components: The client, which is built into PrimalScript Enterprise, and a remote service that must be deployed to each computer where you will remotely run scripts. RSEE is capable of deploying a script from within PrimalScript out to remote computers, where the script is executed, and bringing the scripts’ output and results back to PrimalScript for your review.

The Remote Script Execution Engine™ is only available in PrimalScript Enterprise

118 RSEE is a complex tool, and it interacts closely with Windows’ security subsystems. RSEE is recommended for use only by experienced Windows administrators who fully understand service deployment and management, cross- computer security and authentication, and in the case of domain environments, Group Policy objects and Active Directory administration. Apart from the guidelines in this manual, SAPIEN Technologies cannot assist you with security issues caused by improper configuration, nor can we assist with Active Directory, Group Policy, or local computer configuration tasks.

RSEE is designed only for Windows Script Host (WSH) scripts in VBS (VBScript) or JS (JScript) files. It is not designed for other WSH scripts (including WSFs), nor is it designed for scripts written in other languages (such as batch, KiXtart, and so forth).

RSEE Deployment RSEE’s service component is packaged in a Microsoft Windows Installer (MSI) file, and is suitable for deployment via Group Policy. You can also manually install it on individual machines. Keep in mind that, once installed, the service needs to be started in order to be useful; this will occur automatically after restarting the computer on which the service is installed (the service is set to start automatically by default).

119 After deploying the service, there are a number of configuration steps that you must take in order to properly configure RSEE in your environment.

Identity RSEE installs, by default, to log in under the privileged LocalSystem account. This may be sufficient for your purposes. However, when deploying scripts in PrimalScript Enterprise, be sure not to specify any credentials in the Launch dialog box. Also be advised that the LocalSystem account may not be able to execute some scripts, depending on their security requirements. We recommend that you configure the RSEE service to run under a user account that has administrative privileges on the local computer. In a workgroup environment, this would be a local account, and we recommend creating the same local account (with the same password) on all of your computers, for consistency. In a domain environment, we recommend creating a single domain account, which has local administrative rights on all computers in the domain, and using this account to run the RSEE service. Whenever the RSEE service is running under a user account, you must specify that account (and its password) when deploying scripts in PrimalScript Enterprise.

When using RSEE, you have the option to specify the credentials under which the script should execute. Generally speaking, you need to provide the same credentials that the RSEE service is using to log on.

TCP Port The RSEE service defaults to using TCP port 9987 for incoming connections, and TCP port 9988 for outgoing connections. It is your responsibility to ensure that any local firewalls will permit incoming traffic on this port. Keep in mind that the Windows Firewall (Windows XP SP 2 and later, and Windows Server 2003

120 SP 1 and later) can be centrally configured via a domain Group Policy object. You can specify a different port: • Via the Registry. The key is HKEY_LOCAL_MACHINE\Software\Policies\Sapien. The Value name is InPort (for the incoming port) and OutPort (for the outgoing port). Note that these values are most easily configured by means of a Group Policy object (GPO), and we provide a template (ADM file) that can be imported into a GPO to configure RSEE.

Both PrimalScript Enterprise (as the RSEE client) and the RSEE service utilize InPort and OutPort. The service listens to InPort for incoming connections, and uses OutPort to send script output back to the client. The client reverses this: Scripts are sent via InPort and results are received on OutPort. The registry key above configures these ports for both clients and the service.

Domain Tips While manually configuring a few computers in a workgroup is not a hardship, manually configuring an entire domain of computers can be burdensome. An Active Directory domain environment provides a number of capabilities for centralizing and automating this configuration, however. While this section is not intended as a comprehensive tutorial in Active Directory (we recommend that you consult an experienced Active Directory administrator or the appropriate documentation if you need more assistance), the following tips should help you configure RSEE more easily: • Create a domain account. Name this account something like “RSEEUser” and provide it with a

121 strong password per your organization’s password policies. • Deploy the RSEE service. This can be done by means of a Group Policy object (GPO), linked to the appropriate levels in the domain. The RSEE service defaults to running under the LocalSystem account, and it defaults to port 9987. The service’s MSI is located in the RSEE folder, under your PrimalScript Enterprise installation folder. • Make the RSEE service account a local Administrator. You can do this in a Group Policy object (GPO). Browse to Computer Configuration > Security Settings > Restricted Groups. Add a group (“Administrators”), and then add your RSEE domain account (and any other appropriate accounts) to the group. • Configure the RSEE service. You need to configure the RSEE service to log on with the user account (and password) you created. This can either be done manually, or using a script. The book Windows Administrator’s Automation Toolkit, for example, contains a script which can set the logon account and password used by services running on multiple computers. Utilities like Service Explorer (www.scriptlogic.com) can perform the same task. • Select the TCP port. We provide a Group Policy object (GPO) administrative template (ADM file), which you can import into a GPO and use to centrally configure the TCP port used by the RSEE service. This ADM file is located in the RSEE folder, under your PrimalScript Enterprise installation folder.

Using RSEE To deploy the current script (only VBS and JS files are possible) to one or more remote computers that have the RSEE service installed, click the RSEE button on the Script toolbar, or select Run Script on Remote Computer from the Script menu.

122 RSEE performs a quick scan of your script to look for commands that might create a graphical user element, such as the VBScript MsgBox() function. If it finds any of these functions, it displays a warning message. Keep in mind that scripts will not normally be able to interact with the desktop environment on remote computers, meaning there would be no way for someone to respond to graphical elements such as MsgBox() or InputBox(). As a result, these elements can cause the script to “hang” and stop responding. RSEE does not perform an exhaustive check for graphical elements; it is your responsibility to ensure they’re not used in your scripts. RSEE will allow you to continue with graphical elements, because you may have configured the RSEE service to interact with the desktop of the remote computer. It’s your decision. Next is the RSEE Launch dialog. The Launch dialog lists the computers where your script will be deployed. Note that the Launch dialog always preloads a default list of computer names at startup. Here’s what you can do: • Click Launch to run the script on the computers which have a checkmark next to their name. • Set or clear the checkbox next to one or more computer names. You can leave names in the list, but clearing their checkbox will prevent RSEE from attempting to run the script on them. • Click Close to close the Launch dialog. If you’ve changed the list of computer names, you’ll be prompted to save your changes. • Use Load List and Save List to load an alternate list of computer names (from a text file) or save the current list to a text file. • Use Select All and Unselect All to set or clear the checkbox next to all computer names currently in the list. • Select a computer name and click Remove to remove it from the list.

123 • Type a computer name (must be resolvable to an IP address by your computer) or IP address and click + to add that computer to the list. • Specify a username (user ID) and password. These will be used to run the script on the remote computer, and should generally match the username that the remote RSEE service is using to log in. Note: If the username you specify is a local account on the remote computer(s), then just type the username. If the username is a domain account, specify the name in the format user@domain. The older domain\user format is not supported. When you click Launch, RSEE will execute the script on the remote computer(s). Any output produced by the script will be displayed in the Output tab, within the PrimalScript window. Note that the message “Socket connection failed” indicates that RSEE was unable to connect to the RSEE service on a specified computer (either because the computer is not connected to the network, has a firewall blocking the RSEE service ports, or the RSEE service is not installed).

124 RSEE deploys scripts asynchronously. That is, RSEE sends the scripts out to the remote computers you’ve selected, and then displays whatever results come back. If your scripts produce no output, then you won’t see any results in PrimalScript.

It’s possible for the RSEE service on a remote computer to run into a problem (particularly security- related ones) that it can’t report back; in these instances, it will seem to you (looking at PrimalScript) as if nothing has happened. Whenever possible, your scripts should incorporate error-checking and –trapping, and should produce appropriate output so that you get some results back if the script executes correctly.

Note that RSEE cannot be used to deploy a script for later execution. If you need to schedule a script to execute on a remote computer at a particular time, use Windows’ built-in Task Scheduler instead of RSEE. You can even write a script, utilizing the Win32_ScheduledTask WMI class, that creates remote scheduled tasks on multiple computers. Also note that, if an Output tab is already open in PrimalScript, RSEE will utilize it rather than creating a new one. You will need to manually select the tab to view any RSEE results or error messages.

125 RSEE Restrictions In order to bring the output of remote scripts back to your computer, the remote RSEE service captures the standard command-line output of your scripts. That means any script output must be created using the WScript.Echo method. Do not use graphical user interface functions such as MsgBox() or InputBox(). Because the RSEE service doesn’t interact with the desktop, nobody will ever see these functions’ dialog boxes, and the script will hang.

It is possible, if the RSEE service is running under the LocalSystem account, to configure Windows to allow the service to interact with the desktop. You may wish to experiment with this configuration, but it is not a recommended configuration because of the usual security restrictions on the LocalSystem account.

Also keep in mind any object methods—such as WScript.Popup—which create graphical elements, and avoid these methods. Any objects referenced by a script must be installed, registered, and available on the remote machine where RSEE executes the script. At this time, RSEE can only be used to execute Windows Script Host scripts. RSEE explicitly launches scripts under CScript.exe, which must be available on the remote computers. Most other restrictions in RSEE are actually Windows security restrictions. When the RSEE service launches, it does so using the credentials you configure in Windows’ service manager. When the RSEE service receives a script, it creates a brand-new process, using whatever credentials you enter into the RSEE 126 Launch dialog. The following figure illustrates this process, and the three sets of credentials involved:

Credentials #3: Service Credentials #2: Entered Script RSEE Service RSEE Launch Dialog

` Script

Credentials #1: Credentials #2: Yours Used RSEE Credentials and Execution Process

Always bear in mind that your scripts execute under the security credentials you provide (Credentials #2 in the diagram). This process does require your attention, as several things can go wrong if you’re not careful: • If, in the Launch dialog, you specify credentials (#2 in the diagram) that the RSEE service account (#3 in the diagram) doesn’t have permission to use in a new process launch, then script execution will fail.

Practically speaking, the credentials you provide in the Launch dialog (#2 in the diagram) need to be the same as the credentials the RSEE service uses to log in (#3 in the diagram).

• If the RSEE service account (#3 in the diagram) doesn’t have appropriate rights (including “Log on as a service”), then the RSEE service will not be able to start. • If your script tries to do something that the Launch credentials (#2 in the diagram) don’t have permission to do—such as log into a database or access a file 127 share—then you’ll receive an error. Depending on the exact situation, this may or may not be communicated back to you in PrimalScript. • If your scripts tries to perform an illegal operation— such as specifying alternate credentials in a WMI connection (which is illegal, because the script is executing locally on the remote machine, and local connections to WMI aren’t allowed to use alternate credentials)—you’ll receive an error. Again, depending on the exact circumstances, this error may or may not be fed back to you in PrimalScript. These and other similar situations are not problems with RSEE; they are inherent conditions of the Windows operating system and its security subsystems. Whenever you encounter an error with RSEE, bear these conditions in mind and think about the possible security ramifications of what your script is trying to do.

RSEE Notes RSEE encrypts scripts during transmission to help keep them secure. RSEE does not implement any sort of IP filtering capability (which might, for example, allow you to ensure that only your computer can utilize RSEE on remote servers). Instead, we recommend using Windows’ own built-in IP filtering (available as part of Windows’ IPSec features). Using this filtering, you can ensure that only specified IP addresses are allowed to communicate on the TCP ports used by the RSEE service, thus restricting who can contact that service and utilize RSEE.

128 Chapter 15: The Visual Query Builder

The Visual Query Builder provides a graphical interface for constructing SQL language queries. The tool operates similarly to graphical query builders present in Microsoft products, such as Microsoft SQL Server’s administrative tools. The Visual Query Builder is only available in PrimalScript Enterprise

Visual Query Builder is available on the Tools menu. When you begin using it for the first time, it opens in a new tab and has no preconfigured database connections.

Visual Query Builder does not utilize the same connection list as the Database Browser.

129

Starting the Visual Query Builder

Creating a Database Connection To create a new database connection, select New Connection from the Database menu (this menu will only be visible in the menu bar when the Visual Query Builder’s tab is selected).

Creating a new connection

130 After creating the basic connection, you will need to specify the SQL language dialect that your database supports.

Specifying a SQL language dialect

In most cases, ANSI SQL/92 will work; however, if something more specific to your database is listed, you should use that.

Creating a Query To add tables or other objects to your query, simply drag them from the database browser pane (lower-right) to the relationships pane (upper-left). To remove a table, right-click its title bar in the relationships pane and select Remove.

131

Working with queries

To work with queries: • To include columns in your query, simply check them in the relationships pane. To create new relationships (expressed in the query as JOIN statements), drag the column name from the key (source) table (in the relationships pane) to the related column in the dependent table. • In the columns pane (middle-left), you can specify column name aliases, table (object) name aliases, sort criteria, GROUP BY options, and selection criteria (expressed in the WHERE clause of the query). • You can directly edit the SQL language query using the SQL pane (bottom). • To change a relationship, right-click the relationship’s “connector” line and select edit.

Testing and Using Queries To test a query, select Execute from the Database menu. A dockable Query pane will display the query results.

132 To use your query in a script, select one of the Translate options from the Query menu (note that the VB option will work for VBScript, as well). This will copy the query, in a string variable, to the Windows Clipboard; from there you can paste it into your script.

Customizing the Query Builder Select Query Builder Properties from the Database menu to adjust properties of the Query Builder itself. A number of self- explanatory options are available. Some of these options customize the appearance of the Query Builder; others are more advanced options for changing the way the Query Builder handles certain advanced database functions. You should avoid modifying these advanced options unless you have a strong background in database development and understand their impact.

133 Chapter 16: Working with XML Documents in the Visual XML Editor

The Visual XML Editor is only available in PrimalScript Enterprise

The Visual XML Editor provides a graphical user interface for working with XML-formatted documents. You can also work on XML documents in the standard text editor, if you prefer, and switch back and forth between the two modes. Starting a new XML document, or opening an existing XML document, opens the Visual XML Editor by default.

134

Visual XML Editor

To switch to text mode, right-click the XML document root and select Edit as text file. When in text mode, simply right-click in the code editor and select Open as XML file to return to the visual editor.

Using the Visual XML Editor

Most of the actions discussed here can be activated from the XML toolbar, the XML menu, or by right-clicking in the visual editor area.

XML documents consist of elements, which can have attributes. The primary function of the Visual XML Editor is to allow you to manipulate these elements and attributes visually. You can add elements and attributes, remove elements and attributes, insert elements, repeat an existing element (essentially a shortcut for copying and pasting it, allowing you to repeat it however many times you want), and so forth. When you select an element, its

135 attributes and comments are displayed in the right-hand pane, where you can edit their values. For example, here you can see an open document with one element (in addition to the default Root element), which has one attribute. The attribute’s value is open for editing.

Editing an attribute

Repeating Elements One of the editor’s most useful features is the ability to repeat existing elements. Simply right-click the element and select Repeat element from the context menu to display the Repeat Element dialog box.

136

Repeating an Element

Here, you can specify a new name for the element, if desired, and indicate which attributes will be copied. You also have the option to copy the attributes’ values into the repeated elements, and you can specify how many copies you want made.

137 Chapter 17: Scriptable COM Components

PrimalScript includes a collection of scriptable COM components (called “PrimalToys”) which can be used by any COM-compatible scripting language, such as JScript, VBScript, KiXtart, and others. These components provide a variety of functions that aren’t provided in most scripting languages, helping to make your scripts more flexible and capable. The package of COM components is continually revised, and the current components include: • INI File Access. A component which provides access to configuration information stored in simple textual INI files. • Process Control. A component which provides control over running processes on a Windows system. • File Dialog. A component which provides simple File Open and Save As dialog boxes.

138 In order to make these components easier to deploy within your organization, they are packaged in a Windows Installer (MSI) file located in the Redistributables folder of your PrimalScript installtion. This MSI can be assigned via Group Policy so that these objects will be available wherever your scripts are executed.

INI File Access Component INI files are organized into sections, with name/value pairs. For example: [Section] Key=Test Key2=1 [Section2] Key=Test Key2=1 The component’s ProgID is PrimalScript.IniFile. It provides several methods: • GetProfileString(section, key, default, file) Returns a string value from the specified key, in the specified section, of the specified file. If the key is not found, the specified default value is returned. • GetProfileInt(section, key, default, file) Returns a numeric value from the specified key, in the specified section, of the specified file. If the key is not found, the specified default value is returned. • WriteProfileString section, key, value, file Writes the specified string value to the specified key, in the specified section of the specified file.

139 • WriteProfileInt section, key, value, file Writes the specified numeric value to the specified key, in the specified section of the specified file. • DeleteKey section, key, file Deletes the specified key from the specified section of the specified file • DeleteSection section, file Deletes the specified section from the specified file • FlushINICache file Flushes the INI cache for the specified INI file • GetProfileSection(section, file) Retrieves an entire section from the specified file. This method returns the number of keys which were found in the section; you can then use the KeyValuePairs property to access the keys and their values. • GetProfileSectionNames(file) Retrieves a list of section names from the specified file. This method returns the number of sections found. You can use the Sections property to access the list of section names. • WriteProfileSection section, data, file This method writes the specified data into the specified section of the specified INI file. The data should be an array of “key=value” strings. The component provides two properties: • Sections. This property is an array of section names, available after executing the GetProfileSectionNames method. • KeyValuePairs. This property is an array of key=value strings. After executing GetProfileSection, it will contain the key/value pairs for the section retrieved. Each pair is a string in the format “key=value.” The following script demonstrates the use of this component with an INI file named E:\Test.ini:

140 Dim obj WScript.Echo "Test" set obj = WScript.CreateObject("Primalscript.IniFile")

obj.WriteProfileString "Section","Key","Test","e:\test.ini" obj.WriteProfileInt "Section","Key2",1,"E:\test.ini" obj.WriteProfileString "Section2","Key","Test","e:\test.ini" obj.WriteProfileInt "Section2","Key2",1,"E:\test.ini"

Dim NumKeys Dim Pair

NumKeys = obj.GetProfileSection("Section","E:\test.ini") WScript.Echo NumKeys

For i = 0 To NumKeys‐1 Pair = obj.KeyValuePairs(i) WScript.Echo Pair Next

Dim KeyValue

KeyValue = obj.GetProfileString("Section","Key"," ","E:\test.ini") WScript.Echo KeyValue KeyValue = obj.GetProfileInt("Section","Key2",0,"E:\test.ini") WScript.Echo KeyValue This component depends on IniAccess.dll, which must be installed and registered on the computer where any scripts utilizing this component will run.

Process Control Component This component provides process enumeration and basic control capabilities. The component’s ProgID is PrimalScript.ProcessEnum. Your first use of the object should be to call the Enumerate method, which accepts no parameters and which returns the number of processes currently running. A Processes property is an array of process names, while a ProcessID property is an array of process ID numbers. Neither property is populated before you call the Enumerate method. The IsRunning(procID) method accepts a process ID and returns True if that process is running, or False if it isn’t. The 141 TerminateProcess(procID) method terminates the process whose ID is passed in procID. The GetExitCode(procID) method returns the exit code of the specified process ID. Here’s a sample script that lists all running processes: Dim obj Dim Max Set obj = WScript.CreateObject("Primalscript.ProcessEnum")

Max = obj.Enumerate()

Dim Counter

For Counter = 0 To Max ‐ 1 WScript.Echo obj.Processes(Counter) Next This component depends on ProcessEnum.dll, which must be installed and registered on the computer where any scripts utilizing this component will run.

File Dialog Component This component provides a File Open and Save As dialog. Its ProgID is PrimalScript.FileDialog. The component has the following methods and properties: • AllowMultiSelect. This property can be set to True or False to allow or disallow multiple file sections in a File Open dialog. • CreatePrompt. If this property is set to True and the user enters a filename which does not exist, the user will be prompted to ensure they wish to create the file specified. • DefaultExtension. This property can be set to the default filename extension to be used by the dialog box, such as “txt”. • ExtensionDifferent. After the user closes the dialog, this property will be set to True if the user provided a different filename extension that the one specified by DefaultExtension.

142 • FileMustExist. Is this property is set to True, the user must specify a file which already exists. • FileOpenDialog(). This method displays the File Open dialog. • FileSaveDialog(). This method displays the File Save dialog. • Filter. This property is a string, which specifies the available file types in the dialog’s file type drop-down list. You can specify multiple extensions. For example:

"Text files (*.txt)|*.txt|Word files (*.doc)|*.doc||"

This specifies two file types. The first part of each file type (“Text files (*.txt)”) will be displayed in the drop- down list box, while the second part (“*.txt”) is the actual filename extension. Be sure to include two vertical bars at the end of the string. You can also specify multiple file extensions for a single type:

"All text files|*.vbs;*.txt;*.rtf||"

This example will match any of the three file extensions provided. • FilterIndex. This property sets the currently-selected filter. The first part (“Text files|*.txt”, for example) is 1, the second is index 2, and so forth. • HideReadOnly. This property may be set to True or False to hide or display hidden files in the dialog. • InitialDir. This property can be set to the initial folder that the dialog should start in when it displays. • InitialFileName. This property can be set to the initial filename which the dialog will contain. • NoChangeDir. If set to True, this property prevents the user from changing folders in the dialog.

143 • NoDereferenceLinks. If set to True, this property prevents shortcuts from being “dereferenced,” or expanded to their actual location. Instead, the shortcut file itself will be targeted. • NoLongNames. If this property is set to True, it forces the use of 8.3 filenames. • NoNetworkButton. Set this property to True to hide the network connections button in the dialog. • NoReadOnlyReturn. This property will be set to True if the user did not check the “Read Only” check box and the file is not in a write-protected folder. • NoTestFileCreate. If this property is set to True, a test file will not be created before the dialog is closed. You should specify True is the application saves the file on a create-nonmodify network share. When set to True, the component will not check for write protection, a full disk, or other conditions. Set this property to False and the component will ensure that the file specified in the dialog can be opened and written to. • NoValidate. Set this property to False to disallow invalid filename characters. • NumFilesSelected. This property contains the number of files selected by the user. • OverwritePrompt. Set this property to True to prompt users to overwrite existing files if one is selected. • PathMustExist. Set this property to True to only allow the user to enter a path which actually exists. • ReadOnly. Set this property to True to initially select the “Read Only” checkbox in the dialog. • SelectedFiles. This property is a string array of selected files. • ShareAware. Set this property to True and any errors resulting from network sharing violation problems will be ignored.

144 • Title. This property sets the title of the dialog. The following script demonstrates the use of this component: Dim obj Dim numFiles Dim counter

Set obj = WScript.CreateObject("Primalscript.FileDialog") obj.HideReadOnly = vbTrue obj.Title = "Try to open that file" obj.InitialDir = "C:\Program Files" obj.InitialFileName = "desktop.ini" obj.Filter = "Chart Files (*.xlc)|*.xlc|Worksheet Files (*.xls)|*.xls|Data Files (*.xlc;*.xls)|*.xlc; *.xls|All Files (*.*)|*.*||" obj.FilterIndex = 4 obj.ShowHelp = vbTrue obj.AllowMultiSelect = vbTrue obj.FileOpenDialog numFiles = obj.NumFilesSelected

WScript.Echo "Selected Files" WScript.Echo numFiles For counter = 0 To numFiles ‐ 1 WScript.Echo obj.SelectedFiles(counter) Next

obj.Title = "Try to save that file" obj.FileSaveDialog This component depends on FileDialog.dll, which must be installed and registered on the computer where any scripts utilizing this component will run.

Login Dialog Box Component This component provides a login dialog that collects a username and a password. Its ProgID is PrimalScript.LoginDlg. The component has the following methods and properties: • ShowDialog. This method shows the login dialog box. The properties of this component are not valid until this method has been called. • UserName and Password. These properties contain the username and password entered into the dialog.

145 • WasOK. This property will return True if the user clicked OK in the dialog, otherwise this property will contain False.

This component displays a graphical dialog box. Even if your script runs under a command- line script host like WSH CScript.exe, the dialog will display graphically.

ASP Debugging Component This component provides unique way of debugging Web applications. The components ProgID is PrimalScript.ASPOutputDebug. The component is designed to send trace or debug messages to PrimalScript on a specified port. PrimalScript must be configured to receive these messages, which it will display on an Output tab. To do so, select Options from the Tools menu. Under Debugging, select the checkbox to Enable Windows Socket Debug Messages and specify a port number.

Debugging options

146 You may need to create an exception so that the Windows Firewall, or other local firewall software, will permit PrimalScript to receive traffic on the port you specify.

The component has the following methods and properties: • Initialize “host”, port. This method initializes (opens) the port debugger by connecting to the specified host on the specified port (which must match the one in the PrimalScript configuration). • SocketWait. This property configures the number of milliseconds the component will wait for PrimalScript to respond to the initialize request. You should normally leave this at its default value. • Connected. This property returns a True or False, indicating whether or not the component is connected to PrimalScript. • Close. This method closes the connection to PrimalScript. • Error. This property indicates the status of the last operation: o 0: No error o 1: Failed to allocate a free port on the sending side o 2: Failed to create a port on the sending side o 3: Failed to connect o 4: Failed to send message • OutputDebugString “string”. This method sends the specified string to PrimalScript. You must first use the Initialize method to open the connection.

147 Chapter 18: Automating PrimalScript

Previous versions of PrimalScript included a macro recording capability that provided for basic automation of tasks within PrimalScript—recording and playing back keystrokes, for example. However, the underlying Windows functionality that enabled the macro recorder was removed from Windows Vista. In PrimalScript 2007, an all-new, more robust automation system was introduced.

.psCmd files Essentially, this new system consists of text files with a .pscmd filename extension. These files can contain PrimalScript commands—basically giving you a “scripting language” used to automate PrimalScript itself. You typically begin a .pscmd file by having it open a normal script file—one that you want to edit. The .pscmd file then goes on to “play” whatever commands you tell it. In many cases, the commands in the .pscmd file may raise dialog boxes. Dialog boxes often cannot be directly automated, in which case you’ll need to manually fill-in the dialog box. After you close the dialog, the .pscmd file will continue running. In some cases, the commands may accept parameters, which allow the command to execute without raising a dialog box that you must manually complete. Here is an example .pscmd file that opens a “template,” copies its code, closed it, creates a new file, and pastes in the template code: 148 // NewFile.PSCmd // creates a new file with a custom template inserted //‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ FileOpen("C:\Custom Header.vbs"); // your own custom template EditSelectAll(); // select all EditCopy(); // copy selection FileClose(); // close that header file FileNew(); // create a new file JumpToLine(0); // jump to beginning of file EditPaste(); // paste header into newly created file // end file Notice that // is used as a comment character, and that all lines end in a ; semicolon—much like C-style scripting languages such as Javascript. psCommands .pscmd files are filled with psCommands—essentially macro commands which trigger some built-in PrimalScript functionality. Some psCommands accept arguments—if you omit the arguments, then the command will simply display the associated dialog box.

You’ll notice that most psCommand names reflect the names of the corresponding menu options in the product.

Here is a complete list of available commands: psCommand Function AboutPrimalScript() Display program information, version number and copyright Add Reference() Adds a reference to an assembly or a COM component to the current project AddExistingItem() Adds an existing file to the current project AddFolder() Adds a folder to the current project AddNewItem() Adds a new file to the current project AddToSourceControl() Add the current file to source control AliasToCmdlet() Alias to Cmdlet ANSI_TO_OEM() Converts ANSI characters to OEM characters 149 psCommand Function AppendToClipboard() Appends current selection to Clipboard BackupProjectFiles() Creates a backup of all project files BuildProject() Builds the current project BuildWorkspace() Builds all files in the current workspace CheckForUpdatesNow() Checks if there is a newer version of PrimalScript available CheckIn() Check In CheckInPending() View Pending Check-ins CheckOut() Check out CheckSpelling() Checks the spelling of text ClearAllBookmarks() Clear all bookmarks in the active window Clipboard() Start the clipboard viewer CloseWorkspace() Closes current workspace CmdletToAlias() Cmdlet to Alias CommandShell() Starts a command shell CompareToAnotherFile() Compares this file to another file CompileCheckScript() Compiles/Syntax checks the current script CompleteWord() Completes the current statement ConfigurationManager() Edits the current projects configurations ConnectFolder() Connects a folder to a Source Control Project CreateRegion() Create a persistent folding region Customize() Customize various PrimalScript settings CycleClipboardRing() Cycles the Clipboard Ring and pastes the new item DebugActiveJob() Debug current script job DebugActiveProject() Debug Active Project DebugBreak() Breaks into the debugger DebugGo() Start the current script in the debugger DebugRestart() Restarts the script being debugged DebugRunToCursor() Runs the program to the line containing the cursor DebugScript() Debug the current script with the specified debugger DebugStepInto() Step into the next statement DebugStepOut() Steps out of the current function DebugStepOver() Steps over the next statement DeleteAllBreakpoints() Delete all breakpoints Downloads() Connects to the SAPIEN downloads page EditCopy() Copy the selection and put it on the Clipboard EditCut() Cut the selection and put it on the Clipboard EditFind() Find Text EditFind(what, flags)* Finds the specified text EditPaste() Paste selection from Clipboard EditRedo() Redo last action EditReformat() Reformats the selection to a new line 150 psCommand Function length EditReplace() Replace specific text with different text EditReplace(what, replace,flags)* Finds and replaced the specified text EditSelectAll() Select the entire document EditUndo() Undo last action Exit() Quit the application; prompts to save documents ExpandAll() Expand all items in outline ExploreFTPSites() Open FTP explorer FileClose() Close the active document FileCloseAll() Closes all documents FileInsert() Inserts a Disk File into the currently active window FileNew() Creates a New File FileOpen() Opens a File FilePrint() Print the active document FilePrintPreview() Display full pages FilePrintSetup() Change the printing options FileProperties() Displays File Properties FileSave() Save the active document FileSaveAll() Saves all documents FileSaveAs() Save the active document with a new name FindInFiles() Invokes search for a string or a regular expression across multiple files FindInFiles(what, dir, project, Find the specified text in files fileTypes, flags)* FindNext() Find Next Text FindPrevious() Find Previous Text Font() Change the font for the current window FormatBulletLines() Create a bullet list from the selected lines FormatNumberLines() Numbers the selected lines FTPFileSave() Saves current file to FTP location FTPGet() Gets a file from a FTP location FTPOpen() Opens a FTP Connection FTPPut() Uploads a file to a FTP location FTPSaveAs() Saves current file to FTP location with a new name GenerateTypeLibrary() Generates a type library for the active component GetLatestVersion() Get the latest version of the current file from Visual SourceSafe GlobalBookmarks() Edits global bookmarks HideAll() Hide all items in outline HTMLValidator() Starts the HTML Vallidator Import() Import items into source control IncrementalSearch() Search for an Expression incrementally IndexandContents() List Help topics InvertCase() Inverts the case of the selection 151 psCommand Function JumpToLastEditPosition() Jumps to the last editing position in the current file JumpToLine() Jumps to a specific line JumpToLine(line) Jumps to the specified line number KeyboardMap() Displays all keyboard commands ListMembers() Brings up the completion list box MailAllOpenFiles() Mails all open files MailCurrentFile() Mails the current active File MatchBrace() Find corresponding brace NewWindow() Open another window for the active document NextBookmark() Move to the next bookmarked line OEM_TO_ANSI() Converts OEM characters to ANSI characters OpenFile(name) Opens the specified file OpenRecentFile() Opens recent file OpenRecentProject() Opens recent Project OpenRelatedFile() Opens a Related Files OpenWorkspace() Open Workspace Options() Change program options OutlineExpandAll() Expand all items in outline OutlineHideAll() Hide all items in outline ParameterInfo() View Parameter Info for the selected object PlayMacro() Plays a .pscmd file PlayMacro(file) Plays the specified .pscmd file PowerShell() Opens a PowerShell Window PreviousBookmark() Move to the previous bookmarked line PreviousError() Move to the line containing the previous error PrimalScriptHomepage() PrimalScript Homepage PrimalScriptManual() Launch PrimalScript Manual Program() Select the program to run ProjectNew() Creates a New Project PublishActiveProject() Publish the project to the current transfer target PublishChangesInActiveProject() Publishes changed file in the project to the current transfer target PublishToMultipleTargets() Publish the project to multiple transfer targets RecycleBin() Opens the recycle bin ReformatXML() Reformat the current xml file RefreshStatus() Refresh Source Control Status RegisterActiveComponent() Registers the active component RegisterProduct() Registers your copy of PrimalScript with SAPIEN Technologies, Inc. ReleaseCachedTypeLibraries() Release Cached Type Libraries RemoveFromSourceControl() Remove the files from source control RemoveLicense() Removes all licensing information on this computer. 152 psCommand Function ReplaceInFiles() Replace in Files RunActiveJob() Run current script job RunActiveProject() Run Active Project RunScript() Run script with the specified scripting engine RunScriptOnRemoteComputer() Execute script on other machines SAPIENHomepage() SAPIEN Technologies, Inc. Homepage SaveFilesAsGroup() Saves open documents as a Filegroup SaveScriptEncoded() Saves the script encoded using the Microsoft Script Encoder SaveWorkspace() Saves current workspace SaveWorkspaceAs() Saves workspace with a new name ScriptPackager() Invokes the Script Packager SearchInfoNexus() Search the info nexus SelectText(start, end) Selects the specified text SetActiveConfiguration() Current Configuration SetArguments() Allows you to enter the arguments passed to a script launched in the debugger Settings() Edits the project build and debug settings ShowDifferences() Shows the changes made to a file since it was checked out ShowFileHistory() Shows File History ShowHiddenCharacters() Toggles the visibility of blanks, tabs and newline characters ShowHistory() Shows the history of a file or files under source control SignScript() Signs the current script file SortLinesAscending() Sort the selected lines ascending SortLinesDescending() Sort the selected lines descending SourceControl() Invokes the Source Code Control system SourceControlProperties() Shows a file's source control properties SpacesToTabs() Converts spaces to tabulator characters where possible StopDebugging() Stop debugging the current script TabsToSpaces() Converts tab characters to the correct amount of spaces ToDecimal() Converts the selection to a decimal number ToggleBookmark() Toggle a bookmark for the current line ToggleBreakpoint() Insert/Remove Breakpoint ToggleHexadecimalDisplay() Toggle hexadecimal display ToggleOutline() Toggle outline ToggleOutline() Toggle Outline ToggleStatusBar() Show or hide the status bar ToHexadecimal() Converts the selection to a hexadecimal number ToLowercase() Converts the selection to lowercase letters 153 psCommand Function ToOctal() Converts the selection to an octal number ToUppercase() Converts the selection to uppercase letters UndoCheckOut() Undo Check Out UnregisterActiveComponent() Unregisters the active component Update() Updates items to Latest from Source Control URLDecode() URL Decode URLEncode() URL Encode ViewBuild() Views the Build Window ViewCallStack() Views the Call Stack Window ViewClassBrowser() Shows the Class Browser ViewColumnRuler() Toggles the visibility of column ruler ViewDatabaseBrowser() Shows the Database Browser ViewDebug() Views the Debug Window ViewFileBrowser() Shows the File Browser ViewFindInFiles1() Views the Find In Files 1 Window ViewFindInFiles2() Views the Find In Files 2 Window ViewFullScreen() Toggles full screen mode On and Off ViewHelp() Views the Help Window ViewHTMLXMLBrowser() Shows the HTML/XML Browser ViewInfoBrowser() Shows the Info Browser ViewLineNumbers() Toggles the visibility of line numbers ViewNextError() Move to the line containing the next error ViewOutput() Views the Output Window ViewQueries() Views the Query Window ViewResourceBrowser() Shows the Resource Browser ViewResultsList() Shows the result list window ViewSnippetsBrowser() Shows the Snippets Browser ViewTaskBrowser() Shows the Task Browser ViewToolsBrowser() Shows the Tools Browser ViewTypeLibraryBrowser() Shows the Type Library Browser ViewVariables() Views the Variable Window ViewWatch() Views the Watch Window ViewWithInternetBrowser() Launches your Internet Browser to view the current HTML file ViewWorkspaceBrowser() Shows the Workspace Browser VisualQueryBuilder() Opens the Visual Query Builder

*For psCommands that accept parameters, use the following guide: • What: The string you are searching for • Replace: The replacement string • Dir: The directory; can be blank if specifying Project

154 • Project: The project (must be opened in PrimalScript) name to search; can be blank if specifying Dir • fileTypes: Wildcard mask (*.*, *.vbs, etc.) Finally, the Flags parameter accepts a pipe-delimited list (FLAG1|FLAG2|FLAG2) of the following options: • CQ_WHOLE_WORDS – whole words only • CQ_CASE_SENSITIVE – search is case-sensitive • CQ_REG_EXPRESSION – search term is a regular expression • CQ_ALL_OPEN_DOCS – search all open documents • CQ_REPLACE_CONTROL_CHAR – replace control characters • CQ_SUBFOLDERS – recurse subfolders • CQ_USE_PANE_2 – place results in second pane • CQ_BINARY – search binary files • CQ_KEEP_EXISTING_RESULTS – keep existing search results • CQ_BACKUP_FILES – back up changed files • CQ_DIRECTION_UP – search up (default is down) • CQ_PROJECT – search project

155 Appendix A Keyboard Shortcuts

This appendix documents the default keyboard shortcuts included with PrimalScript. You can, of course, modify these by using the Customize option from the Tools menu.

Cursor movement

Key Function Up arrow Moves cursor one line up Down arrow Move cursor one line down Left arrow Moves cursor one character to the left Right arrow Moves cursor one character to the right Home Move cursor to beginning of line First press: Moves to beginning of code or text on line Second press: Moves to physical beginning of line End Move cursor to end of current line Page up Moves the cursor one page (current window height) up Page down Moves the cursor one page (current window height) down Ctrl + up arrow Scroll window one line up. Ctrl + down Scroll window one line down. arrow Ctrl + left arrow Move cursor one word to the left. Ctrl + right arrow Move cursor one word to the right. Ctrl + HOME Move cursor to the beginning of the file. Ctrl + END Move cursor to the end of the file. Alt + down arrow Move down one paragraph (paragraphs are separated by empty lines). Alt + up arrow Move cursor one paragraph up. Ctrl + L Move to a specific line.

156 Selection functions

Key Function Ctrl + A Select all text in window Shift + up arrow Select from current cursor position to character above it. Shift + down arrow Select from current cursor position to character below it. Shift + left arrow Select the previous character Shift + right arrow Select the next character Shift + home Select from current cursor position to beginning of line Shift + end Select from current cursor position to end of line Shift + page down Select down a page (current window height) of text Shift + page up Select up a page (current window height) of text Ctrl + Shift + left arrow Select from current cursor position to the beginning of the word Ctrl + Shift + right arrow Select from current cursor position to the end of the word Ctrl + Shift + home Select from current cursor position to beginning of file Ctrl + Shift + end Select from current cursor position to end of file

Clipboard functions

Key Function - (Numeric Move current line to the clipboard. keypad) + (Numeric Copy current line to the clipboard. keypad) Ctrl + C Copy selection to clipboard. Ctrl + R Replace current word with clipboard contents. Ctrl + Shift + V Cycle Clipboard Ring. Ctrl + V Insert clipboard at current cursor location. Ctrl + X Move (copy and delete) the current selection to the clipboard. Ctrl + INSERT Copy selection to clipboard. Shift + DEL Move (copy and delete) the current selection to the clipboard. Shift + INSERT Insert clipboard at current cursor location. Ctrl + Shift + W Cut current word to clipboard. Ctrl + Alt + W Copy current word to clipboard.

Find Shortcuts

Key Function F3 Find next. Ctrl + F3 Find currently selected item Alt + F3 Search for a string or a regular expression. 157 Key Function Shift + F3 Find previous. Ctrl + D Places the focus into the search combo box in the toolbar Ctrl + F Search for string or a regular expression. Ctrl + Shift + F Find in Files Ctrl + H Search and Replace in the current document or all open documents Ctrl + Shift + H Search and Replace in files, folder or project members Ctrl + I Start incremental search.

Script Shortcuts

Key Function Ctrl + J Expand current word from snippet F7 Run current script. Ctrl + F7 Compile/check script. Shift + F7 Debug current script. F4 View next error Shift + F4 View previous error F5 Debug job Ctrl + F5 Run job

Editing Shortcuts

Key Function Delete Deletes the current selection or the character at the cursor position. Ctrl + Delete Delete the next word. Insert Toggles Insert/Overwrite mode. Alt + Insert Redo Backspace Deletes the character left of the current cursor position. Ctrl + Delete the previous word. Backspace Alt + Backspace Undo the last editing action. Tab Indents the current selection Shift + Tab Un-indents current selection. Alt + left arrow Un-indents current selection. Alt + right arrow Indents current selection by one tab. Ctrl + B Wrap selection in bold tags (Only available in HTML files) Alt + C Capitalize the currently selected word. Ctrl + E Moves the cursor back to the last editing position. Ctrl + Q Comment the current line Ctrl + Shift + Q Uncomments the current line Alt + Shift + Q Single quote the current selection Alt + Q Double quote the current selection Ctrl + T Transposes the current character with the next character. Ctrl + U Lowercase current selection

158 Key Function Ctrl + Shift + U Uppercase current selection. Alt + Y Deletes the current line. Ctrl + Y Redo the last undone action. Ctrl + Z Undo the last editing action.

Window navigation

Key Function Alt + 1 Switch to internal browser window. Alt + 2 Switch to output window. Alt + 3 Switch to Nexus window / rotate through Nexus panes Alt + 4 Switch back to MDI/Editing area Alt + L Toggle left nexus area on/off Alt + R Toggle right nexus area on/off F6 Next pane Shift + F6 Previous pane

Bookmark shortcuts

Key Function F2 Jump to next bookmark. Alt + F2 View global bookmarks. Ctrl + F2 Toggle bookmark at current line. Shift + F2 Jump to previous bookmark.

Project shortcuts

Key Function Ctrl + Shift + A Add a new item to the current project Alt + Shift + A Add an existing item to the current project Shift + Ctrl + N Create a new project from a template or folder Shift + Ctrl + O Open an existing project. F9 Start active project

File shortcuts

Key Function Alt + Enter Show file properties. Ctrl + Shift + M Opens the header file with the same base name as the current CPP file Ctrl + Alt + L Load file under cursor Ctrl + N Open a new, empty editing window. Ctrl + W Closes the active file 159 Key Function Ctrl + O Open an existing file. Ctrl + P Print the current file. Ctrl + S Save the current file to disk. Ctrl + Shift + S Save all open files to disk.

PrimalSense keys

Key Function Ctrl + Space Primalsense complete word Ctrl + Shift + D Goto variable or type declaration Ctrl + Alt + space View parameter list Ctrl + Alt + T List members

Outlining keys

Key Function Ctrl + Shift + Numeric - Collapse all outlines Ctrl + Shift + Numeric + Expand all outlines F8 Toggle current outline on/off

Internal Script Debugger keys

Key Function Ctrl + Alt + F6 Run script in internal debugger Shift + F5 Stop internal debugger Ctrl + Shift + F5 Restart in internal debugger F10 Single step current instruction Ctrl + F10 Run to current cursor location F11 Step into function/sub Shift + F11 Step out of current function/sub F12 Toggle breakpoint at current line Ctrl + Shift + F12 Delete all breakpoints

Miscellaneous

Key Function Esc Cancels current process Ctrl + M Match brace. F1 Help. Shift + F1 Context sensitive help. Alt + F4 Exits the application. Ctrl + Shift + B Switch to CodeBehind file (in ASP.NET files) Ctrl + Alt + I Switch to the current browser View 160 Appendix B Index

Administrative privileges, 12 Clipboard Integration, 37 ADO Wizard, 58 Code coloring, ADSI Wizard, 98 customizing, 74 ADSIConnection class, 99 Code completion, 46 ADSIUser, 100 Code folding, 37 ASP Debugging Code hinting, 46 Firewall Warning, 14 COM Components, 137 ASP Debugging Component, 144 Deploying, 138 asynchronous remote script COM objects in packaged scripts, execution, 124 117 Automating PrimalScript, 148 Command-Line Switches Backup options, 73 Diagnostic, 16 Bookmarks, 35 General, 17 Breakpoints, 105 Community, 56 Browser Comparing Files, 76 Class, 56 Compiling scripts, 101, 112 Database, 58 Alternate Credentials, 116 File, 56 Encoding and Signing, 116 HTML Navigation, 58 Components Info, 53 ASP Debugging, 144 Resources Browser, 56 File Dialog, 141 Snippets, 57 INI File Access, 138 Tasklist Browser, 53 Login Dialog, 145 Tools, 56 Process Control, 140 Type Library Browser, 54 Connection strings Workspace, 53 Copying from a connection, 58 XML Navigation, 58 Context-sensitive help, configuring, Build Toolbar, 28 84 Case correction, 46 Conversion Features, 43 Checking Spelling, 76 Converting Class Browser, 56 case, 44 Class/object lists, 47 character sets, 44 161 decimal, octal, and hexadecimal, Firewall 44 Ports used, 13 spaces and tabs, 44 Firewall Warnings uppercase and lowercase, 44 ASP Debugger, 13 URLs, 44 Remote Script Execution Converting data, 43 Engine, 13 Core Editor Features, 34 Update Checking, 13 credentials used by RSEE, 126 Web access, 13 Customizing PrimalScript, 71 foldable regions Database Browser, 58 automatic, 37 database connection, creating in named, 38 Visual Query Builder, 129 persistent, 38 Database Wizard, 58 temporary, 38 Debugger Formatting Features, 44 Breakpoints, 105 FTP, 77, 110 Built-in, 104 Basic Capabilities, 77, 111 Evaluating expressions, 108 Built-in client, 110 External, 103 FTP Toolbar, 26 Installation and Security, 104 graphical user elements and RSEE, PrimalScope, 104 122 Querying object properties, 107 Group Policy object, adminstering Running Scripts, 106 RSEE with, 121 Variable and object properties, Help 107 Configuring context-sensitive, 84 Debugging, 103, 106 Using and configuring, 83 Debugging Toolbar, 20 Using MSDN Library, 85 Default directories, 72 VBScript, 85 Directories, default, 72 Windows PowerShell, 85 Document tab options, 73 hexadecimal, displaying scripts in, Edit Toolbar, 21 36 Editions, 8 hidden characters, displaying, 36 Encoding, 97 HTML /XML Navigator Browser, 58 Encoding or decoding URLs, 44 HTML Toolbar, 25 Encoding packaged scripts, 116 Infinite Undo, 49 Evolved Script Packager, 112 Info Browser, 53 Alternate Credentials, 116 Info Toolbar, 29 Encoding and Signing, 116 INI File Access Component, 138 Expressions, evaluating, 108 Installation External Debuggers, 103 Security requirements, 12 File Browser, 56 IntelliSense, 46 File Dialog Component, 141 Internet Toolbar, 28 File groups, 31 License File Groups, 72 Registering, 15 File History, 50 Removing, 16 File Toolbar, 19 Live syntax checking, 48 Files Local mode, 65 Grouping, 31 LocalSystem, RSEE and, 120 Find, 40 Login Dialog Component, 145 Find in Files, 42 Macro recording, 148 Results, 42 Master mode, 65 Find Toolbar, 22 Member lists, 46

162 Microsoft Visual SourceSafe, 78 Replace, 41 MSDN Library Integration, 85 Resources, 56 multi-target publishing, 67 RSEE, 118 Network credentials, 126 Ports used, 13 Deployment, 119 New Features, 10 Restrictions, 125 Numbering, Line and Columns, 34 RSEE service, 120 Packaging scripts, 101 Running Projects, 67 Packaging Scripts, 112 Scanning for tools, 14 Alternate Credentials, 116 Script Debugging, 103 Encoding and Signing, 116 Script Encoding, 97 Panes, 30 Script executables, 71 Docking, making into tabs, 31 Script packager, 112 PrimalDiff, 76 Script types, 113 PrimalScope, 104 Script Packager, 101 PrimalSense, 46 Script Signing, 96 customizing, 49, 75 Script Toolbar, 23 PrimalSense code coloring, Search and Replace, 40 customizing, 74 Basic, 40 PrimalSense Toolbar, 24 In Files, 42 PrimalToys, 137 Regular Expression, 41 Deploying, 138 Service Releases, 11 Print options, 72 Signing packaged scripts, 116 Process Control Component, 140 Signing scripts, 96 Projects Skin, 32 Backing Up, 67 Snippets Managing Items, 63 Customizing the location of, 57 Properties, 64 Using, 57 Publishing, 66 Snippets Browser, 57 Publishing to multiple Source control destinations, 67 CVS and Subversion, 79 Running, 67 Troubleshooting, 82 Source Control, 63 Using with CVS, 81 Starting, 60 Source Control, 50 Suggested Workflow, 61 Using, 80 Workspace management, 62 Visual SourceSafe, 78 Queries Source Control Toolbar, 27 building SQL language, 128 Spell check, 76 Connecting to database, 129 SQL queries, 128 Testing and copying, 131 standalone executable, 101 Query builder, 128 Stop Debugging, 107 Recording macros, 148 Syntax checking, 48 Recycle Bin, 49 Syntax coloring, 46 Reformatting, 44 Syntax hints, 47 Registering, 15 Tabs, 30 Registration, 15 Task List, 53 Regular Expression, 41 Tasklist Browser Remote Script Execution Engine, Customizing, 54 118, 127 TCP port, RSEE usage, 120 Firewall Warning, 13 Technical Support, 11 Remote scripting, 118, 127 Text editor options, 74

163 To Do List, 53 Visual XML Editor, 133, 134 Toolbar What's New, 10 Build, 28 Win32, 98 Customizing, 70 Windows PowerShell Debugging, 20 Configuring Snap-Ins, 95 Edit, 21 PrimalSense for cmdlets, 96 File, 19 Profiles in PrimalScript, 95 Find, 22 Windows Script Files, 91 FTP, 26 Windows Script Host options, 75 HTML, 25 Windows Script Host TrustPolicy, Info, 29 96 Internet, 28 Windows Scripting Features, 87 PrimalSense, 24 Windows Vista Script, 23 Security requirements, 12 Source Control, 27 Wizards View, 22 ADSI, 98 Toolbars and Shortcut keys, Database, 58 customizing, 70 WMI, 97 Tools Browser, 56 WMI Wizard, 97 Scanning for Tools, 14 Workspace Browser, 53 TrustPolicy, 96 Workspace Management, 62 Type libraries, 75 WSC Files, 91 Type Library Browser Browser, 54 Adding code, 94 Undo, 49, 50 Creating, 92 Universal Help, 83 Properties, Methods, and Updated, 11 Events, 94 User Account Control, 12 Registering and unregistering, User Interface 95 Colors and Layout, 32 Type libraries, 95 Customizing, 14 Viewing as XML, 92 Saving and sharing settings, 33 Workspace Management, 92 Tab Style, 32 WSF Files, 87, 91 user interface elements Adding code, 91 locations, 18 Arguments, 90 Tabs and Panes, 30 Creating, 87 username, format for using with Properties, 90 RSEE, 124 Viewing as XML, 88 Variable lists, 47 Workspace Management, 88 Variables and Object Properties, XML Examining, 107 Editing, 133 View Toolbar, 22 XML documents, working with Visual Query Builder, 128 visually, 134 Visual SourceSafe, 78

164