WINDOWS SCRIPTING INTEGRATION GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2017 Copyright Notice

©2016 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, , GEOVIA, , 3D VIA, BIOVIA and are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.

Acknowledgments and References

To print photographs or files of computational results (figures and/or data) obtained using BIOVIA software, acknowledge the source in an appropriate format. For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations were performed with the DMol3 program, and graphical displays generated with Pipeline Pilot."

BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to [email protected], or in writing to:

BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA Contents

Chapter 1: Introduction 1 Property List Interface 19 Windows Script Host (WSH) 1 Interface Methods for Data, Globals and General Requirements 1 Parameters Objects 19 Additional Information 2 Chapter 8: Handling Errors 23 Chapter 2: Scripting Components 3 Reporting Errors in VBScript 23 VBScript Components 3 Reporting Errors in Python 23 VBScript Requirements 3 Chapter 9: Debugging Scripts 25 VBScript Component Parameters 3 Line Number Information 25 VBScript Examples 4 MsgBox() in VBScript 26 Viewer Examples 4 Server-Side Debugging 26 Calculator Examples 4 Writing the Debug Output to a File 26 Filter Examples 4 Writing the Debug Output to a Property 26 Generator Examples 4 Chapter 10: Script Writing for Web Service Protocols 27 Dialog Examples 4 Python Component 6 Python Scripting Requirements 6 Python Component Parameters 6 Python Examples 6 Chapter 3: Scripting Guidelines 7 Selecting a Scripting Language 7 Granularity of Scripting Components 7 Planning for Change 7 Chapter 4: Editing Scripting Components 9 Editor Toolbar Buttons 9 Viewing Available Methods 9 Viewing Method Signatures 10 Viewing Calculable Properties 10 Finding Text 11 Chapter 5: Scripting Component Settings 13 Scripting Parameters 13 Initial Script 13 Script 14 Final Script 14 Created Data Class Name Parameter 14 Setting Icon and Ports 14 Chapter 6: Modes of Use 16 Chapter 7: Scripting Objects and API 17 Scripting Objects 17 Data 17 Globals 17 Parameters 17 Component 17 Component Properties 17 Component Methods 18 Chapter 1: Introduction

You can enhance the capabilities of Pipeline Pilot by using scripts in your protocols. Scripting allows you to build customized components that access and modify the content of each data record and global protocol data. Components are available in the Integration collection for designing your own custom components. This guide shows you how to use the scripting components that are based on Windows Script host (WSH). You can use both VBScript and Python script syntaxes with the components covered in this guide. Note: Cross-platform component development is also supported in the Integration collection for and Java. Details are covered in other user guides in this document set. Scripting components provide a way to program component behavior, with access to: Client- and server-side software packages that support COM automation Pre-existing script or GUI utilities that you can integrate with Pipeline Pilot Client As a component designer, you have access to the contents of each data record passed to the script component and to the relevant parameter and global settings. This allows you to write components such as data readers, data writers, data filters, and calculators. You can employ the full range of intrinsic functions built into the specific scripting language, and incorporate functionality from the range of public modules available for the specific scripting language.

Windows Script Host (WSH) The VBScript and Python scripting components are dependent on scripting engines written for the Windows Script Host (WSH). WSH is a tool that is included in later releases of the Windows operating system, Internet Explorer, and Windows 2000 Server (for use with login and standalone scripts). WSH creates an environment for hosting scripts. When a script is run, WSH plays the part of the host—it makes objects and services available for the script and provides an environment within which the script is executed. WSH supports scripting to the Windows platform, allowing you to run scripts from both the Windows desktop and the command prompt. Its scripting capabilities are more powerful than batch files; scripts running in the WSH environment can leverage the power of WSH objects and other COM-based .

General Requirements To use scripting components, you need the separately licensed Integration collection. The scripting components require the following third-party software: Third-party scripting engines that support components for Perl, VB, and Python implemented using Windows Script Host (WSH). These applications may need to be installed on both the server and client. The Integration collection includes the required scripting engines for Perl. To work with the scripting components and manipulate the program data, you need experience writing scripts in the language supported by the component, and you need to know about the objects made available to the scripting engines and the scripting interface that each exposes. For example, there are some simple component properties that define the behavior of the scripting component (which determine if it is a data reader, a filtering component, etc.)

Introduction | Page 1 For Python scripting support, you need to install the WSH engine for Python, freely available as a part of the Python for Windows installation from Active State at http://www.activestate.com/activepython.

Additional Information For more information about the Pipeline Pilot Integration collection and other BIOVIA software products, visit https://community.3dsbiovia.com.

Page 2 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 2: Scripting Components

The Integration collection includes the following Windows scripting components: VBScript (on Client) VBScript (on Server) Python (on Server)

Notes: From the Components tab, the VBScript components are available in "Database and Application Integration\Application Integration\Programmatic Integration". Python (on Server) is a prototype (due to a memory leak issue with the Python WSH module). It is located in "Database and Application Integration\Prototypes\Application Integrators".

VBScript Components VBScript is a scripting language for Microsoft platforms. It is included with Internet Explorer on Windows platforms and is well-suited for automating external applications, because it includes syntax to interact with COM components. VBScript cannot run on its own; it must be hosted by another application (such as Internet Explorer or a VBScript component). The Integration collection's VBScript components are ideally suited for writing client- and server-side scripts that automate visualization tools such as Microsoft Office programs, data graphing tools, and your own custom dialogs. The following VBScript components are available in the Integration collection: VBScript (on Client): Targeted at GUI components that need to interact with users on their own systems (for example, to display dialogs or results in Excel). VBScript (on Server): Intended for non-graphical, non-blocking operations, such as accessing a COM automation application that does not require user interaction. VBScript Requirements To employ a VBScript component, you need to have some experience using VBScript to write scripts. For more information on the basics of writing VBscripts, see Microsoft's VBScript documentation at http://msdn.microsoft.com/en-us/library/t0aew7h6.aspx. Note: Visual Basic (VB) is not the same as VBScript, although they share much common syntax. VB is a programming language for developing standalone applications and libraries and is outside the scope of scripting in Pipeline Pilot Client.

VBScript Component Parameters To define the behavior of a scripting component, you write lines of script for one or more of the three parameters: Initial Script, Script, and Final Script, explained in Scripting Parameters. (Detailed information about how to set the parameter values is also available when you have a VBScript component open in Pipeline Pilot Client's script editor, which is designed to supply you with information as you need it.)

Scripting Components | Page 3 You can also add you own custom parameters to allow protocol authors to modify the behavior of your VBScript component. VBScript Examples Pipeline Pilot includes example protocols that illustrate how to use the VBScript components. These protocols include help and highlight points of interest. We recommend that you read the comments and help for each protocol before using them. You may find it productive to use the examples as a template for your own scripting components. Note: From the Protocol tab, the VBScript examples are available in "Examples\Integration\Integrating Applications\Scripting Examples". Viewer Examples Simple Excel Automation: Use VBScript as a COM automation client. It contains a subprotocol for driving Excel to load data and format the appearance of the worksheet. Spotfire Viewer Example: Use VBScript as a COM automation client; the VBScript component automates Spotfire Decision Site. Three properties are calculated from a data stream and displayed as a 3D Scatter plot. VBScript Writer and Viewer: Shows how to create simple writer and viewer components with VBScript. Calculator Examples Simple VBScript Manipulator: This example demonstrates how to use a VBScript component as a data manipulator VBScript RegExp Property Calculator: Uses the regular expression capabilities of VBScript to analyze the SMILES textual molecular representation. Filter Examples Validation Example: Filters data records by validating the data types or values. These VBScript components may be useful in validating data entered by users before further processing. VBScript Simple Filter: Filtering on data record properties, and routing data to the Pass or Fail port. Generator Examples Alphabet Generator: Generates letters of the alphabet using VBScript. File List Reader Example: Generates a listing of file system files and folders with options for filtering the list content. Dialog Examples File Browser Dialog Box: Implements a simple file browser in VBScript. Login Dialog Box: Includes a VBScript component to display a prompting dialog box. Message Dialog Box: Includes a VBScript component that shows a simple message box. Multiline Text Entry Dialog Box: Display a custom user interface window, defined in HTML and JavaScript. The dialog box can be used to enter or paste multi-line, delimited text as a source of data for a pipeline. Radio Button Dialog Box: Includes a VBScript component that displays another more complex, custom dialog box.

Page 4 | Pipeline Pilot • Windows Scripting Integration Guide The dialog examples (Multiline Text Entry Dialog Box and Radio Button Dialog Box) makes use of an object named SciTegic.HtmlGUI to display a dialog box based on an HTML description of the layout and behavior. This object is a script-compatible wrapper around the Windows function ShowHTMLDialog(). For any non-trivial behavior, the HTML will need to include JavaScript (or VBScript if browser portability is not a concern) to minimally process the input and output data for the dialog. To define the behavior of a scripting component, you write lines of script for the three parameters: Initial Script, Script, and Final Script, explained in Scripting Parameters. (Detailed information about how to set the parameter values is also available when you have a VBScript component open in the Pipeline Pilot script editor. The editor is designed to supply you with information as you need it.) SciTegic.HtmlGUI Properties Your script can set the following properties on the object before displaying the dialog using the ShowModalDialog() method, described below. Property Name Description Url The location of the HTML document used as the dialog description. Typically, your script will compose this from an implementation parameter value and write it to a temporary file. DialogLeft The pixel coordinate for the left side of the dialog. DialogTop The pixel coordinate for the top side of the dialog, measured from the top of the screen. Scrollbars True if the dialog should contain scrollbars. Default is false. Resizable True if the dialog should be resizable. Default is false. Status True if the dialog should include a status bar. Default is false.

Note: Note: The dialog width and height are best defined in the dialog itself, as in the example .

SciTegic.HtmlGUI Methods

Method Name Return Value Description ShowModalDialog(input_data) The return value is The user interface defined any data output from by the HTML is displayed as the HTML dialog, as a blocking dialog box. The defined by the input_data parameter is window.returnValue used to pass a simple value in the script of the or an object to the dialog. HTML resource. This This is retrieved in the may be an object, a dialog as the simple value or there window.dialogArguments may not be a return property. value, depending on Pass an empty variable if the function of the no input data is required. dialog.

Scripting Components | Page 5 Note: Arbitrarily complex data may be passed both ways between the VBScript and the HTML dialog by passing and/or returning the Scripting.Dictionary object, a standard data structure in the Windows scripting runtime used to hold name-value pairs.

Python Component Python is a scripting language distributed for Windows by ActiveState (http://www.activestate.com/activepython) along with a script engine for Windows Script Host (WSH). Python is useful for interfacing with OO Libraries such as CORBA, and there are many downloadable modules available for Python scripts (for example, those listed at the Python Programming Language web site (http://www.python.org). The Python scripting component, Python (on Server), is designed for the integration of server-side tools. It uses the Python scripting engine to run the scripts defined for the component and is configured to run on the server machine. Python Scripting Requirements To employ a Python component, you need to have some experience using Python to write scripts. To run Python scripts, you need to have a Python installation on the machine where the scripting component runs. You can download a version of Python for Windows from ActiveState (http://www.activestate.com/activepython). Note: The small per-record memory leak in the Python WSH engine can be a problem for handling large numbers of records within a single protocol.

Python Component Parameters To define the behavior of a scripting component, you write lines of script for one or more of the three parameters: Initial Script, Script, and Final Script, explained in Scripting Parameters. (Detailed information about how to set the parameter values is also available when you have a Python component open in the Pipeline Pilot Client script editor. The editor is designed to supply you with information as you need it.) You can also add your own custom parameters to allow protocol authors to modify the behavior of your Python component. Python Examples Pipeline Pilot's examples include protocols that illustrate how to use the Python scripting component. These protocols include help and highlight points of interest. We recommend that you read the comments and help documentation for each protocol, to help you use them as templates for your own scripting components. From the Protocols tab, search for "Python". The following examples are available: Call a REST Service With Python Example: Demonstrates how to call a REST service from a simple Python script. Python Record Filter Example: Demonstrates how easy it is to implement a filter component using Python script and route the data records to the appropriate ports. Send Email via Python script: Shows how to implement simple business logic in an IronPython script using external Python functionality, in this example sending an email.

Page 6 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 3: Scripting Guidelines

Each scripting language has its own rich support environment, so it is not easy to make hard and fast rules about the most suitable context for each language. The skill set and the experience of the person working with the scripting component is probably one of the more important considerations.

Selecting a Scripting Language Follow these guidelines to select the most suitable scripting language: Components that run on the client should employ VBScript. This does not require any special installation on a Windows system, and specifically, the development of custom user interface components should be deployed using the VBScript (on Client) component. VBScript provides a natural environment for accessing COM services, although Python is also well equipped in this respect. Python is a more object-oriented scripting language and may be a better choice for interfacing with OO libraries such as CORBA and .NET. There are also domain-specific open-source toolkits such Biopython (http://biopython.org/wiki/Main_Page) that might direct you toward a particular scripting language.

Granularity of Scripting Components Not only does the scripting language offer a wealth of functionality, but also it offers the ability to integrate other modules and programs. A single component may encapsulate a significant amount of functionality, making it extremely powerful. How much functionality should you include in a single component? The rule of thumb is reusability. This is the same for all forms of custom component building, whether using PilotScript, third-party scripting, or building a new component as a subprotocol. Design your components so you can leverage their functionality for a variety of purposes. If a component contains too much specific functionality, it is unlikely to be useful elsewhere. If the same functionality is divided among several components that run sequentially, it’s more likely that at least one of them might be reusable in another context. There are other constraints, such as the functionality of an external service used by a component. However, potential reuse of your component is a good guideline to consider when designing scripting components.

Planning for Change When publishing a component for general use, consider what will happen when you need to fix a bug or add a new feature. For any users incorporating a component in a protocol, how easily can they adopt the new enhancement? Many of the components that we deploy are written in compiled code that is upgraded whenever Pipeline Pilot is updated. In this way, enhancements to the components are automatically adopted by any component running on the latest version of the server software. The key to this approach is that the functionality of the component is deployed separately from the user interface definition that is saved in

Scripting Guidelines | Page 7 the protocol database (XMLDB). You can also use an approach that employs a similar strategy. In this way, the implementation may be upgraded for the benefit of all protocols that incorporate that component. Here are a few alternate suggestions: Write your script code in a library and reference it from the component. For example, in the case of VBScript, set up the component to reference a separate script file that contains functions called from the component script itself. You can find these types of examples in some of our deployed components. You can collapse a component into a subprotocol and expose some or all of its parameters by promoting parameters to the parent level. Since a subprotocol component is deployed as a subprotocol shortcut, any updates to the underlying component are adopted up by each shortcut to that component in an existing protocol.

Page 8 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 4: Editing Scripting Components

Use the Script dialog in Pipeline Pilot Client to edit script syntax for VBScript and Python scripting components supported by Windows Script Host (WSH). This editing interface is analogous to that available when you work with Perl or PilotScript scripting components. The editor supports syntax styling, error indicators, script completion, and call tips ("intellisense"). An auto-completion feature speeds up script development by reducing the amount of keyboard input on your part. Help is available directly in the function name to guide you as you enter script syntax. As you begin typing a function or variable name, the editor automatically suggests completions of variable and function names. You can either accept the suggestion by pressing ENTER or continue typing the name.

Editor Toolbar Buttons Toolbar buttons are available that can help simplify your editing, and shortcuts are provided to help you enter syntax. Use the toolbar buttons in the script editor to do the following: Button Description Cut, Copy, Paste selection

Print the syntax to your printer Undo and Redo the last commands

Find and Replace syntax Go to a specific line Show/hide line numbers Show/hide folding of logical constructs Enable/Disable line wrapping Zoom in/Zoom out

Tip: You can save changes to your scripts as you continue to modify syntax by clicking the Apply button (you do not need to close the editor to save your changes). Any changes you apply to the script are also reflected in the Parameter window. If you try to modify parameters while the script editor is open, you will not be able to apply your changes until the protocol job is done.

Viewing Available Methods To view a list of available methods to use with the expression: 1. Enter the scripting object (Data, Component, Parameters, Globals) followed by a period (.). A list of available methods is displayed. 2. Make a selection from the drop-down list. (Press your down-arrow key to move through the list and to highlight methods.)

Editing Scripting Components | Page 9 Drop-down list of calculable properties

Viewing Method Signatures To view a method signature with its relevant parameters and returns: Enter an open parenthesis.

Method signature, parameters, and returns

Viewing Calculable Properties To view a list of calculable properties to use with the expression:

Page 10 | Pipeline Pilot • Windows Scripting Integration Guide Press F4 and select from the list.

List of calculable properties

Finding Text To find text within expression syntax: 1. Click Find. The Find dialog opens. 2. In Find what, enter the text. To find text that matches the exact words you enter (and not include what you enter as part of a longer word), select Match whole word only. To find a text that uses specific capitalization, select Match case. Click Find Next.

Find dialog 3. Repeat until you find the text.

Tips: If you close the dialog and want to find another occurrence, press F3. If you want to replace an occurrence with a different word or phrase, click Replace. To find syntax on a specific line number:

Editing Scripting Components | Page 11 1. Click Go To Line. The Go To Line dialog opens. 2. In Line, enter the line number. 3. Click Go To.

Go To Line Dialog Note: The right-click menu provides shortcuts to most of the above features.

Page 12 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 5: Scripting Component Settings

Scripting Parameters The following script content parameters are used with WSH-supported scripting components: Script: Runs once for each data record; accesses individual data records. Use this parameter to run a script once for each data record sent into to the component. Initial Script: Runs once before any data arrives; useful for file access, initialization of globals, etc. Use this parameter to run the script only once, when setting up the component. Final Script: Runs one time after all data is processed; useful for cleanup, aggregate data processing, etc. Use this parameter to run a script only once, when the component is shutting down. The Script dialog includes tabs for working with all three scripting parameters, as illustrated below.

Script dialog Initial Script Use Initial Script to run the script only once, when setting up the component. For a component that works with data input or output, the initialization phase might include tasks that do the following: Open a file Declare variables Read component parameters Create an instance of an automation server object If a component is designed to accomplish a single task instead of processing input or output data, its entire logic may be in the Initial Script section. Examples include scripts that do the following: Display a single GUI box at the start of a protocol Perform a one-time reading of a temporary file into a visualization tool Convert one file format to another as a precursor to subsequent data processing

Scripting Component Settings | Page 13 Note: Record data is not accessible to the scripting component in its Initial Script phase. Global protocol data and component parameters are accessible during all phases.

Script A script used with this parameter runs once for each data record that is sent to the component. In the case of a data generator component, Script is invoked continually, until the component registers that its task is complete. Typically, the Script parameter is where the following operations take place: Data records are analyzed and amended New data records are populated (in the case of a data generator) Data records are filtered, based on content Data record content is exported to a file Note: Record data is only accessible to the scripting component during its Script parameter phase. Global protocol data and component parameters are accessible during all phases.

Final Script Any script used with this parameter runs only one time, when the component is shutting down. For a component that works with data input or output, the finalization phase might include tasks that do the following: Close a file Release all object references If a simple component is designed to accomplish a single task, rather than process input or output data, its entire logic can reside in the Final Script parameter. This approach is identical to the analogous use of Initial Script parameter, described previously. The Initial Script and Final Script parameters are semantically identical in this case, since there is no intervening data input. Note: Record data is not accessible to the scripting component in its Final Script parameter phase. Global protocol data and component parameters are accessible during all phases.

Created Data Class Name Parameter Created Data Class Name is another parameter used with the WSH scripting components. When you are designing a scripting component as a data generator (for example, a file reader), this parameter needs a value. Valid values are available from a drop-down list. In most cases, you can set the value to "SciTegic.PropertyList". It defines a general-purpose set of name-value pairs. This is the class of data structure used in many applications. If you do not set this value for a data generator component, an error message about a null data item is displayed when your script tries to set up property values for the new data record.

Setting Icon and Ports Since a scripting component is used for customization purposes, ensure that the icon and port settings are appropriate, based on their purpose. A number of icons are available, so use the one that most closely represents the component's function. If the component is a data generator rather than a data

Page 14 | Pipeline Pilot • Windows Scripting Integration Guide consumer, turn off the input port. If the script does not set the component return code to FailData, turn off the Fail port.

Scripting Component Settings | Page 15 Chapter 6: Modes of Use

You can construct some broad categories of components using scripting languages that define the type of behavior that the component exhibits. For each category, there is a standard set of rules for working with the ProcessState and ReturnCode of the component object. It is through this interaction that a component functions as a data reader, data filter, and so on. The component usage categories are listed below. Each category includes a description of how to work with the Component object properties. If a section is blank, no special action is needed with respect to these object properties. Component Usage Component.ProcessState Component.ReturnCode Calculator manipulates the data passing through the component) Filter (directs data to either the Pass or For records to be passed Fail port) to the filter's Fail port: Component.ReturnCode = FailData Reader/Simple Generator (generates a At initialization: number of new data records and then Component.ProcessState stops) = ReadyToCreateData When all data is generated: Component.ProcessState = DoneProcessingData Amplifier (generates a number of new For each input: data records for each data record input) Component.ProcessState = ReadyToCreateData When all data is generated for a single input: Component.ProcessState = ReadyForData Writer (exports data content to external If data is to be removed storage) after export: Component.ReturnCode = DeleteData

Modes of Use | Page 16 Chapter 7: Scripting Objects and API

The scripting component framework provides component scripts with access to certain data and control structures. This is achieved by defining a number of objects that are available to any script that you write for a scripting component. Therefore, within your script, you can invoke the methods and properties on these objects.

Scripting Objects The scripting objects that you can use in your scripts include: Data Globals Parameters Component Data Represents the current data record. It makes sense to access this object during the Script phase of the component execution. This is when data records are processed. At initialization and finalization, the Data object is empty. Globals The set of global protocol properties defined for the context of the scripting component. It consists of any global values defined by other third-party and PilotScript components and the parameters of any protocol that are containers of the scripting component. Parameters The set of parameter values defined on the scripting component. You can add new component parameters to the basic set, and then use those new parameters to define the behavior of your script. This process is known as "parameterization". We recommend that you practice reusing existing components. Note: The above objects have a property list interface described below.

Component This object has two important properties used by the script to coordinate its behavior with the scripting framework and two methods. Component Properties

Property Data Type Property Values ProcessState Long ReadyForData: The script is ready to process data records (the default). Integer ReadyToCreateData: The script is to generate new data records. DoneProcessingData: The script is not generating any more data records.

Scripting Objects and API | Page 17 Property Data Type Property Values ReturnCode Long PassData: The current data record is to flow out of the Pass port (the Integer default). FailData: The current data record is to flow out of the Fail port. DeleteData: The current data record is to be deleted (data does not exit the component).

Note: How these properties are used depends on the mode of the script component, whether it is a data generator, data filter, data writer, etc. For details and information about the use of these properties, see Chapter 6 Modes of Use. Component Methods

Calculate Gets the value of a calculable property. Input Parameters: property (String) The name of the calculable property. Return value: None

GetAbsolutePath If the input string is a relative path, it is converted to an absolute path based on the server root location. Use this method to confirm that any URL property of the Parameters object is in absolute form, since these values are often defined relative to the server root. Input Parameters: path (String) A file path (in a relative or absolute form). Return value: The absolute file location.

ExtractAbsolutePathsForReading A reader component uses this API to convert the variety of forms for values in a Source URL parameter into a set of absolute file paths. This single call deals with multiple comma separated paths and wildcard characters. It also maps relative paths to absolute paths by searching through all the package data roots on the server. The return value from this function is always an array, whether the file specification maps to one or multiple URLs. For client-side component use, its functionality is more limited. It deals with breaking up a comma- delimited list of file paths into an array. Input Parameters: pathSpec (String) The file specification that may include multiple paths (relative or absolute) and wildcards (* and ?)

Page 18 | Pipeline Pilot • Windows Scripting Integration Guide ExtractAbsolutePathsForReading Return value: The absolute file locations to which the path specification maps.

GetHTMLGUIProgID If you are creating an HTML dialog object in your script, use this method to get the prog id of the dialog object. This prog id is version specific so you do not use an object from another installation, which may subsequently be uninstalled. A typical pattern looks something like the following (see the dialog scripting examples for more details): ' Set up the dialog Dim dlg Set dlg = CreateObject(Component.GetHTMLGUIProgID()) dlg.URL = tempfile ‘ tempfile was previously populated with the dialog HTML ' Invoke the dialog Dim results Set results = dlg.showModalDialog(dlgArgs)

Input Parameters: None Return value: The prog id to use in your script for creating the HTML dialog object.

Property List Interface The Data, Globals, and Parameters objects all share a property list interface. It provides the capability to get and set property values, and to add new properties. The interface is detailed below. Note: Any set function that references a non-existent property name creates the property. Use IsPropertyDefined() to check for a property's existence before assigning a value.

Interface Methods for Data, Globals and Parameters Objects

GetPropertyValue Get the value of a property. If the property is an array property, then just the first item is returned. Input Parameters: property (String) The name of the property. Return value: The property value.

Scripting Objects and API | Page 19 GetPropertyValues Gets the value of a property as an array. Input Parameters: property (String) The name of the property. Return value: The property value array.

SetPropertyValue Assign a non-array value to a property. Input Parameters: property (String) The name of the property. If it does not exist it is created. Return value: None

SetPropertyValues Assigns an array value to a property. Input Parameters: property (String) The name of the property. If it does not exist it is created. values The array value to be assigned to the property. Return value: None

IsPropertyDefined Checks to see if the named property exists on the property list. Input Parameters: property (String) The name of the property. Return value: (Long Integer) Nonzero if the property exists.

GetNumPropertyValues Requests the size of the array of values for the named property. If the number is greater than 1, then the property is an array property. Input Parameters: property (String) The name of the property.

Page 20 | Pipeline Pilot • Windows Scripting Integration Guide GetNumPropertyValues Return value: (Long Integer) The length of the value item array for the property. The value is 1 for a non-array property.

GetNumPropertiesDefined Returns the number of properties in the property list. Input Parameters: None Return value: (Long Integer) The number of properties in the property list.

GetIthPropertyName Returns the name of property in the property list, where the property is specified by index. This method facilitates looping through all the properties without knowing their names in advance. Input Parameters: propertyIndex (Long Integer) The index of the property to find. The value should be in the range 0 to GetNumPropertiesDefined()-1. Return value: (String) The name of the indexed property.

RemoveProperty Removes the property from the property list. Input Parameters: property (String) The name of the property to be removed. Return value: None

RemoveAllProperties Removes all of the properties in the property list. Input Parameters: None Return value: None

Scripting Objects and API | Page 21 RenameProperty Renames a property in the property list. Input Parameters: oldPropertyName (String) The name of the property to be renamed. newPropertyName (String) The new name of the property. Return value: None

ReorderProperties Reorders properties in the property list. Input Parameters: property (String Array) The array of property names in the desired order. addNew (long) Flag that indicates if new properties in 'property' are to be added to the property list. Sometimes property values that exist in some data records do not exist in all. This flag allows you to control whether such a case is considered to be a data validity error. Return value: None

Page 22 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 8: Handling Errors

This section describes how to report an error from a script component so the server can handle it like other standard component errors and display the error details in a dialog. Example scenarios include: Property is missing from the data record Specified file does not exist Data value is out of range Auxiliary program or module is not installed For any of the above scenarios, it is important to generate an error so the protocol stops running (assuming the component is configured that way). You also need to display a meaningful error message.

Reporting Errors in VBScript To generate an error in a VBScript component, use the Raise method of the intrinsic Err object in VBScript. For purposes of this discussion, the Err.Raise method takes the following useful arguments: Err.Raise number, source, description number: A Long integer subtype that identifies the nature of the error. VBScript errors (both VBScript- defined and user-defined errors) are in the range 0–65535. When setting the number property to your own error code in the VBScript, add your error code number to the constant vbObjectError. For example, to generate the error number 1050, assign vbObjectError + 1050 to the number property. source: A string expression naming the object or application that originally generated the error. Enter the component name or function for this value to emphasize where the error was generated. description: A string expression describing the error. If unspecified, the value in number is examined. If it can be mapped to a VBScript run-time error code, a string provided by VBScript is used as description. If there is no VBScript error corresponding to number, a generic error message is used. Example: If ypt > 1000.0 Then Err.Raise vbObjectError + 9999, _ "Scatter Plot", _ "Data point (" & CStr(xpt) & "," & CStr(ypt) & ") is out of range (Max Y is 1000.0)" End If

Reporting Errors in Python To trigger exceptions in Python, you can use the raise statement. raise error_type, error_data A number of named error types are built into Python. Experienced users may even define their own error types. Below is a list of some potentially useful built-in error types:

Handling Errors | Page 23 Error Type Description IOError Raised when an I/O operation fails IndexError Raised when a sequence subscript is out of range NameError A local or global name is not found RuntimeError A general catchall category ValueError Raised when a function receives an argument of an inappropriate value Example: # Check for a maximum processing limit if Count > 1000: raise ValueError, 'No more than 1000 items may be processed'

Tip: For additional information about Python's built-in error types, user-defined errors, exception handling, and use of the assert statement, read the ActivePython documentation available at http://www.activestate.com/activepython.

Page 24 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 9: Debugging Scripts

This section provides information on how to debug scripting problems for all WSH-supported components (VBScript, Python).

Line Number Information When a script terminates with an error, an error message is displayed. This occurs with syntax errors and run-time exceptions. Most error messages include a line number as illustrated in the following figure:

Errors indicated by line number and error syntax description You can use this number to find the problem in the script expression. The Script dialog for the component includes a Go To Line feature to help you find the specific line in the expression syntax.

Debugging Scripts | Page 25 Feature to find line number in expression editor

MsgBox() in VBScript The MsgBox() function in VBScript displays a blocking text message. During development, this is useful for tracking down problems when running a script. However, this approach is only suitable when the VBScript component is configured to run on the client machine. If the component runs on the server, the message box is displayed on the server and the protocol appears to stop responding on the client.

Server-Side Debugging There are different debug methods you can apply if you need to debug a script running on the server from a client machine. These methods are described below. Writing the Debug Output to a File You can add file write operations to the script to capture debugging information. If you need to capture information for each data record, ensure that you open the file once in the Initial Script and close it in the Final Script. Tip: Your debug file should be in a location that is accessible on your client. You can add a component to the protocol to display the contents of the file after it closes.

Writing the Debug Output to a Property To get more interactive access to debugging output, write text to a data record or global property, and then view the data in the appropriate viewer. Here is an example that uses a global property: Globals.SetPropertyValue("Debug", "CTAB is " & ctab); If this scripting component is followed by the Display Global Properties component, with input and output ports switched on for inline use, then the debug text for each data record is displayed. Note: If there are a significant number of data records, click the Hide button in the Global Properties dialog to suppress the dialog, once it is no longer useful.

Page 26 | Pipeline Pilot • Windows Scripting Integration Guide Chapter 10: Script Writing for Web Service Protocols

There are a few things to keep in mind if your protocol that uses a scripting component is intended to be invoked from a Web service interface (for example, from a web browser). Scripting components have an advanced parameter called Check For NoUI. When set to "True", the default value for VBScript (on Client), the component is not invoked if the protocol is executed via the web service interface, because the protocol has no direct user interface and the scripting component is ignored. When components display a user interface (or generally require access to a client), the general rule is to set the value to "True". However, such a scripting component protocol is not suitable for running as a web service. If necessary, you can maintain such components in your protocol, but ensure that in "non-UI" mode, the protocol checks for the global NoUI global value and provide alternative, non-graphical execution when this flag is set to "True".

Script Writing for Web Service Protocols | Page 27