windows scripting integration guide - Pipeline Pilot

WINDOWS SCRIPTINGINTEGRATION 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, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES arecommercial 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 DassaultSystè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 BIOVIAsoftware, acknowledge the source in an appropriate format. For example:

"Computational results obtained using software programs from Dassault Systèmes BIOVIA. The abinitio calculations were performed with the DMol3 program, and graphical displays generated withPipeline Pilot."

BIOVIAmay grant permission to republish or reprint its copyrighted materials. Requests should besubmitted to BIOVIA Support, either through electronic mail to [email protected], or in writingto:

BIOVIA Support5005Wateridge Vista Drive, San Diego, CA 92121 USA

ContentsChapter 1: Introduction 1Windows Script Host (WSH) 1General Requirements 1Additional Information 2Chapter 2: Scripting Components 3VBScript Components 3VBScript Requirements 3VBScript Component Parameters 3VBScript Examples 4Viewer Examples 4Calculator Examples 4Filter Examples 4Generator Examples 4Dialog Examples 4

Python Component 6Python Scripting Requirements 6Python Component Parameters 6Python Examples 6

Chapter 3: Scripting Guidelines 7Selecting a Scripting Language 7Granularity of Scripting Components 7Planning for Change 7Chapter 4: Editing Scripting Components 9Editor Toolbar Buttons 9Viewing AvailableMethods 9Viewing Method Signatures 10Viewing Calculable Properties 10Finding Text 11Chapter 5: Scripting Component Settings 13Scripting Parameters 13Initial Script 13Script 14Final Script 14

Created Data Class Name Parameter 14Setting Icon and Ports 14Chapter 6: Modes of Use 16Chapter 7: Scripting Objects and API 17Scripting Objects 17Data 17Globals 17Parameters 17Component 17Component Properties 17Component Methods 18

Property List Interface 19InterfaceMethods for Data, Globals andParameters Objects 19

Chapter 8: Handling Errors 23Reporting Errors in VBScript 23Reporting Errors in Python 23Chapter 9: Debugging Scripts 25Line Number Information 25MsgBox() in VBScript 26Server-Side Debugging 26Writing the Debug Output to a File 26Writing the Debug Output to a Property 26

Chapter 10: Script Writing for Web ServiceProtocols 27

Chapter 1:IntroductionYou can enhance the capabilities of Pipeline Pilot by using scripts in your protocols. Scripting allows youto build customized components that access and modify the content of each data record and globalprotocol data. Components are available in the Integration collection for designing your own customcomponents. This guide shows you how to use the scripting components that are based on WindowsScript host (WSH). You can use both VBScript and Python script syntaxes with the components coveredin this guide.

Note: Cross-platform component development is also supported in the Integration collection for Perland 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 automationPre-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 scriptcomponent and to the relevant parameter and global settings. This allows you to write componentssuch as data readers, data writers, data filters, and calculators. You can employ the full range of intrinsicfunctions built into the specific scripting language, and incorporate functionality from the range of publicmodules available for the specific scripting language.

Windows Script Host (WSH)The VBScript and Python scripting components are dependent on scripting engines written for theWindows Script Host (WSH). WSH is a tool that is included in later releases of theWindows operatingsystem, Internet Explorer, and Windows 2000 Server (for use with login and standalone scripts). WSHcreates an environment for hosting scripts. When a script is run, WSH plays the part of the host—itmakes objects and services available for the script and provides an environment within which the scriptis executed.

WSH supports scripting to theWindows platform, allowing you to run scripts from both theWindowsdesktop and the command prompt. Its scripting capabilities aremore powerful than batch files; scriptsrunning in theWSH environment can leverage the power ofWSH objects and other COM-basedtechnologies.

General RequirementsTo use scripting components, you need the separately licensed Integration collection. The scriptingcomponents require the following third-party software:

Third-party scripting engines that support components for Perl, VB, and Python implemented usingWindows Script Host (WSH). These applications may need to be installed on both the server andclient. The Integration collection includes the required scripting engines for Perl.To work with the scripting components and manipulate the program data, you need experiencewriting scripts in the language supported by the component, and you need to know about theobjects made available to the scripting engines and the scripting interface that each exposes. Forexample, there are some simple component properties that define the behavior of the scriptingcomponent (which determine if it is a data reader, a filtering component, etc.)

Introduction | Page 1

For Python scripting support, you need to install theWSH engine for Python, freely available as a partof the Python for Windows installation from Active State athttp://www.activestate.com/activepython.

Additional InformationFor more information about the Pipeline Pilot Integration collection and other BIOVIA softwareproducts, visit https://community.3dsbiovia.com.

Page 2 | Pipeline Pilot • Windows Scripting Integration Guide

http://www.activestate.com/activepython

https://community.3dsbiovia.com/

Chapter 2:Scripting ComponentsThe 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 ApplicationIntegration\Application Integration\Programmatic Integration".Python (on Server) is a prototype (due to a memory leak issue with the Python WSHmodule). It islocated in "Database and Application Integration\Prototypes\Application Integrators".

VBScript ComponentsVBScript is a scripting language for Microsoft platforms. It is included with Internet Explorer on Windowsplatforms and is well-suited for automating external applications, because it includes syntax to interactwith COM components. VBScript cannot run on its own; it must be hosted by another application (suchas Internet Explorer or a VBScript component).

The Integration collection's VBScript components are ideally suited for writing client- and server-sidescripts that automate visualization tools such as Microsoft Office programs, data graphing tools, andyour 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 ownsystems (for example, to display dialogs or results in Excel).VBScript (on Server): Intended for non-graphical, non-blocking operations, such as accessing a COMautomation application that does not require user interaction.

VBScript RequirementsTo employ a VBScript component, you need to have some experience using VBScript to write scripts. Formore information on the basics of writing VBscripts, seeMicrosoft's VBScript documentation athttp://msdn.microsoft.com/en-us/library/t0aew7h6.aspx.

Note: Visual Basic (VB) is not the same as VBScript, although they sharemuch common syntax. VB is aprogramming language for developing standalone applications and libraries and is outside the scopeof scripting in Pipeline Pilot Client.

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

Scripting Components | Page 3

http://msdn.microsoft.com/en-us/library/t0aew7h6.aspx

You can also add you own custom parameters to allow protocol authors to modify the behavior of yourVBScript component.

VBScript ExamplesPipeline Pilot includes example protocols that illustrate how to use the VBScript components. Theseprotocols include help and highlight points of interest. We recommend that you read the commentsand help for each protocol before using them. You may find it productive to use the examples as atemplate for your own scripting components.

Note: From the Protocol tab, the VBScript examples are available in"Examples\Integration\Integrating Applications\Scripting Examples".

Viewer ExamplesSimple Excel Automation: Use VBScript as a COM automation client. It contains a subprotocol fordriving Excel to load data and format the appearance of the worksheet.Spotfire Viewer Example: Use VBScript as a COM automation client; the VBScript componentautomates Spotfire Decision Site. Three properties are calculated from a data stream and displayed asa 3D Scatter plot.VBScript Writer and Viewer: Shows how to create simple writer and viewer components withVBScript.

Calculator ExamplesSimple VBScript Manipulator: This example demonstrates how to use a VBScript component as adata manipulatorVBScript RegExp Property Calculator: Uses the regular expression capabilities of VBScript to analyzethe SMILES textual molecular representation.

Filter ExamplesValidation Example: Filters data records by validating the data types or values. These VBScriptcomponents 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 ExamplesAlphabet Generator: Generates letters of the alphabet using VBScript.File List Reader Example: Generates a listing of file system files and folders with options for filteringthe list content.

Dialog ExamplesFile 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 simplemessage box.Multiline Text Entry Dialog Box: Display a custom user interface window, defined in HTML andJavaScript. The dialog box can be used to enter or pastemulti-line, delimited text as a source of datafor a pipeline.Radio Button Dialog Box: Includes a VBScript component that displays another more complex,custom dialog box.


The dialog examples (Multiline Text Entry Dialog Box and Radio Button Dialog Box) makes use of anobject named SciTegic.HtmlGUI to display a dialog box based on an HTML description of the layoutand behavior. This object is a script-compatible wrapper around theWindows functionShowHTMLDialog(). For any non-trivial behavior, the HTML will need to include JavaScript (or VBScriptif 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 howto set the parameter values is also available when you have a VBScript component open in the PipelinePilot 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 theShowModalDialog()method, described below.

Property Name Description

Url The location of the HTML document used as the dialogdescription. Typically, your script will compose this from animplementation parameter value and write it to atemporary file.

DialogLeft The pixel coordinate for the left side of the dialog.

DialogTop The pixel coordinate for the top side of the dialog, measuredfrom 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 <HTMLid=dlgTextEntry STYLE="width: 350px; height: 430px">.

SciTegic.HtmlGUI Methods

Method Name Return Value Description

ShowModalDialog(input_data) The return value isany data output fromthe HTML dialog, asdefined by thewindow.returnValuein the script of theHTML resource. Thismay be an object, asimple value or theremay not be a returnvalue, depending onthe function of thedialog.

The user interface definedby the HTML is displayed asa blocking dialog box. Theinput_data parameter isused to pass a simple valueor an object to the dialog.This is retrieved in thedialog as thewindow.dialogArgumentsproperty.Pass an empty variable ifno input data is required.

Scripting Components | Page 5

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

Python ComponentPython 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 aremany downloadablemodules available for Python scripts (for example, those listed at the Python Programming Languageweb 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 runon the server machine.

Python Scripting RequirementsTo employ a Python component, you need to have some experience using Python to write scripts. Torun Python scripts, you need to have a Python installation on themachine where the scriptingcomponent 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 handlinglarge numbers of records within a single protocol.

Python Component ParametersTo define the behavior of a scripting component, you write lines of script for one or more of the threeparameters: Initial Script, Script, and Final Script, explained in Scripting Parameters. (Detailedinformation about how to set the parameter values is also available when you have a Pythoncomponent open in the Pipeline Pilot Client script editor. The editor is designed to supply you withinformation as you need it.) You can also add your own custom parameters to allow protocol authors tomodify the behavior of your Python component.

Python ExamplesPipeline 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 thecomments and help documentation for each protocol, to help you use them as templates for your ownscripting 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 simplePython script.Python Record Filter Example: Demonstrates how easy it is to implement a filter component usingPython 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 scriptusing external Python functionality, in this example sending an email.



https://www.python.org/


Chapter 3:Scripting GuidelinesEach scripting language has its own rich support environment, so it is not easy to make hard and fastrules about themost suitable context for each language. The skill set and the experience of the personworking with the scripting component is probably one of themore important considerations.

Selecting a Scripting LanguageFollow these guidelines to select themost suitable scripting language:

Components that run on the client should employ VBScript. This does not require any specialinstallation on aWindows system, and specifically, the development of custom user interfacecomponents should be deployed using the VBScript (on Client) component.VBScript provides a natural environment for accessing COM services, although Python is also wellequipped in this respect.Python is a more object-oriented scripting language and may be a better choice for interfacing withOO 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 ComponentsNot only does the scripting language offer a wealth of functionality, but also it offers the ability tointegrate other modules and programs. A single component may encapsulate a significant amount offunctionality, making it extremely powerful.

Howmuch functionality should you include in a single component? The rule of thumb is reusability. Thisis 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 theirfunctionality for a variety of purposes.

If a component contains too much specific functionality, it is unlikely to be useful elsewhere. If the samefunctionality is divided among several components that run sequentially, it’s more likely that at leastone 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 scriptingcomponents.

Planning for ChangeWhen publishing a component for general use, consider what will happen when you need to fix a bug oradd a new feature. For any users incorporating a component in a protocol, how easily can they adoptthe new enhancement?

Many of the components that we deploy are written in compiled code that is upgraded wheneverPipeline Pilot is updated. In this way, enhancements to the components are automatically adopted byany component running on the latest version of the server software. The key to this approach is that thefunctionality of the component is deployed separately from the user interface definition that is saved in

Scripting Guidelines | Page 7

http://biopython.org/wiki/Main_Page

the protocol database (XMLDB). You can also use an approach that employs a similar strategy. In thisway, the implementation may be upgraded for the benefit of all protocols that incorporate thatcomponent.

Here are a few alternate suggestions:

Write your script code in a library and reference it from the component. For example, in the case ofVBScript, set up the component to reference a separate script file that contains functions called fromthe component script itself. You can find these types of examples in some of our deployedcomponents.You can collapse a component into a subprotocol and expose some or all of its parameters bypromoting parameters to the parent level. Since a subprotocol component is deployed as asubprotocol shortcut, any updates to the underlying component are adopted up by each shortcut tothat component in an existing protocol.


Chapter 4:Editing Scripting ComponentsUse the Script dialog in Pipeline Pilot Client to edit script syntax for VBScript and Python scriptingcomponents supported by Windows Script Host (WSH). This editing interface is analogous to thatavailable when you work with Perl or PilotScript scripting components.

The editor supports syntax styling, error indicators, script completion, and call tips ("intellisense"). Anauto-completion feature speeds up script development by reducing the amount of keyboard input onyour part. Help is available directly in the function name to guide you as you enter script syntax. As youbegin typing a function or variable name, the editor automatically suggests completions of variable andfunction names. You can either accept the suggestion by pressing ENTER or continue typing the name.

Editor Toolbar ButtonsToolbar buttons are available that can help simplify your editing, and shortcuts are provided to help youenter 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 Applybutton (you do not need to close the editor to save your changes). Any changes you apply to thescript are also reflected in the Parameter window. If you try to modify parameters while the scripteditor is open, you will not be able to apply your changes until the protocol job is done.

Viewing Available MethodsTo 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 ofavailable methods is displayed.

2. Make a selection from the drop-down list. (Press your down-arrow key to move through the list andto highlight methods.)

Editing Scripting Components | Page 9

Drop-down list of calculable properties

Viewing Method SignaturesTo view a method signature with its relevant parameters and returns:

Enter an open parenthesis.

Method signature, parameters, and returns

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


Press F4 and select from the list.

List of calculable properties

Finding TextTo 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), selectMatch whole word only.To find a text that uses specific capitalization, selectMatch 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.


Chapter 5:Scripting Component Settings

Scripting ParametersThe 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 ascript 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. Usethis 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 ScriptUse Initial Script to run the script only once, when setting up the component. For a component thatworks with data input or output, the initialization phasemight include tasks that do the following:

Open a fileDeclare variablesRead component parametersCreate an instance of an automation server object

If a component is designed to accomplish a single task instead of processing input or output data, itsentire 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 protocolPerform a one-time reading of a temporary file into a visualization toolConvert 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. Globalprotocol data and component parameters are accessible during all phases.

ScriptA script used with this parameter runs once for each data record that is sent to the component. In thecase of a data generator component, Script is invoked continually, until the component registers that itstask is complete.

Typically, the Script parameter is where the following operations take place:

Data records are analyzed and amendedNewdata records are populated (in the case of a data generator)Data records are filtered, based on contentData 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 ScriptAny script used with this parameter runs only one time, when the component is shutting down. For acomponent that works with data input or output, the finalization phasemight include tasks that do thefollowing:

Close a fileRelease 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 ofInitial Script parameter, described previously. The Initial Script and Final Script parameters aresemantically 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 ParameterCreated Data Class Name is another parameter used with theWSH scripting components. When youare designing a scripting component as a data generator (for example, a file reader), this parameterneeds 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 datastructure used in many applications.

If you do not set this value for a data generator component, an error message about a null data item isdisplayed when your script tries to set up property values for the new data record.

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


consumer, turn off the input port. If the script does not set the component return code to FailData, turnoff the Fail port.

Scripting Component Settings | Page 15

Chapter 6:Modes of UseYou can construct some broad categories of components using scripting languages that define the typeof behavior that the component exhibits. For each category, there is a standard set of rules for workingwith the ProcessState and ReturnCode of the component object. It is through this interaction that acomponent 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 workwith the Component object properties. If a section is blank, no special action is needed with respect tothese object properties.

Component Usage Component.ProcessState Component.ReturnCode

Calculator manipulates the data passingthrough the component)

Filter (directs data to either the Pass orFail port)

For records to be passedto the filter's Fail port:Component.ReturnCode= FailData

Reader/Simple Generator (generates anumber of new data records and thenstops)

At initialization:Component.ProcessState= ReadyToCreateData

When all data is generated:Component.ProcessState= DoneProcessingData

Amplifier (generates a number of newdata records for each data record input)

For each input:Component.ProcessState= ReadyToCreateData

When all data is generated fora single input:Component.ProcessState= ReadyForData

Writer (exports data content to externalstorage)

If data is to be removedafter export:Component.ReturnCode= DeleteData

Modes of Use | Page 16

Chapter 7:Scripting Objects and APIThe scripting component framework provides component scripts with access to certain data and controlstructures. This is achieved by defining a number of objects that are available to any script that youwrite for a scripting component. Therefore, within your script, you can invoke themethods andproperties on these objects.

Scripting ObjectsThe scripting objects that you can use in your scripts include:

DataGlobalsParametersComponent

DataRepresents the current data record. It makes sense to access this object during the Script phase of thecomponent execution. This is when data records are processed. At initialization and finalization, theData object is empty.

GlobalsThe set of global protocol properties defined for the context of the scripting component. It consists ofany global values defined by other third-party and PilotScript components and the parameters of anyprotocol that are containers of the scripting component.

ParametersThe set of parameter values defined on the scripting component. You can add new componentparameters 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 existingcomponents.

Note: The above objects have a property list interface described below.

ComponentThis object has two important properties used by the script to coordinate its behavior with the scriptingframework and two methods.

Component Properties

Property Data Type Property Values

ProcessState LongInteger

ReadyForData: The script is ready to process data records (the default).

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 LongInteger

PassData: The current data record is to flow out of the Pass port (thedefault).

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 thecomponent).

Note: How these properties are used depends on themode of the script component, whether it is adata generator, data filter, data writer, etc. For details and information about the use of theseproperties, 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 rootlocation. Use this method to confirm that any URL property of the Parameters object is in absoluteform, 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 parameterinto a set of absolute file paths. This single call deals with multiple comma separated paths andwildcard characters. It also maps relative paths to absolute paths by searching through all the packagedata roots on the server. The return value from this function is always an array, whether the filespecification 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 includemultiple paths (relative or absolute) and wildcards(* and ?)


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 thedialog 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 moredetails):

' Set up the dialogDim dlgSet dlg = CreateObject(Component.GetHTMLGUIProgID())dlg.URL = tempfile ‘ tempfile was previously populated with the dialogHTML' Invoke the dialogDim resultsSet 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 InterfaceTheData, Globals, and Parameters objects all share a property list interface. It provides the capability toget 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. UseIsPropertyDefined() 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.


GetPropertyValues

Gets the value of a property as an array.

Input Parameters:


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 iscreated.

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 iscreated.

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:


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, thenthe property is an array property.

Input Parameters:



GetNumPropertyValues

Return value:

(Long Integer) The length of the value item array for the property. The value is 1 for a non-arrayproperty.

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. Thismethod facilitates looping through all the properties without knowing their names in advance.

Input Parameters:

propertyIndex (Long Integer) The index of the property to find. Thevalue should be in the range 0 toGetNumPropertiesDefined()-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


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 desiredorder.

addNew (long) Flag that indicates if new properties in 'property'are to be added to the property list. Sometimesproperty values that exist in some data records do notexist in all. This flag allows you to control whether such acase is considered to be a data validity error.

Return value:

None


Chapter 8:Handling ErrorsThis section describes how to report an error from a script component so the server can handle it likeother standard component errors and display the error details in a dialog.

Example scenarios include:

Property is missing from the data recordSpecified file does not existData value is out of rangeAuxiliary 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 VBScriptTo generate an error in a VBScript component, use the Raisemethod of the intrinsic Err object inVBScript. For purposes of this discussion, the Err.Raisemethod 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 toyour 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 numberproperty.source: A string expression naming the object or application that originally generated the error. Enterthe 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 bemapped to a VBScript run-time error code, a string provided by VBScript is used asdescription. If there is no VBScript error corresponding to number, a generic error message is used.

Example:

If ypt > 1000.0 ThenErr.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 PythonTo 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 ownerror 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 limitif 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, exceptionhandling, and use of the assert statement, read the ActivePython documentation available athttp://www.activestate.com/activepython.



Chapter 9:Debugging ScriptsThis section provides information on how to debug scripting problems for all WSH-supportedcomponents (VBScript, Python).

Line Number InformationWhen a script terminates with an error, an error message is displayed. This occurs with syntax errorsand run-time exceptions. Most error messages include a line number as illustrated in the followingfigure:

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 thecomponent 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 VBScriptThe MsgBox() function in VBScript displays a blocking text message. During development, this is usefulfor tracking down problems when running a script. However, this approach is only suitable when theVBScript component is configured to run on the client machine. If the component runs on the server,themessage box is displayed on the server and the protocol appears to stop responding on the client.

Server-Side DebuggingThere are different debug methods you can apply if you need to debug a script running on the serverfrom a client machine. Thesemethods are described below.

Writing the Debug Output to a FileYou can add file write operations to the script to capture debugging information. If you need to captureinformation for each data record, ensure that you open the file once in the Initial Script and close it inthe Final Script.

Tip: Your debug file should be in a location that is accessible on your client. You can add a componentto the protocol to display the contents of the file after it closes.

Writing the Debug Output to a PropertyTo get more interactive access to debugging output, write text to a data record or global property, andthen 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 theDisplay Global Properties component, with input andoutput 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 theHide button in the Global Propertiesdialog to suppress the dialog, once it is no longer useful.


Chapter 10:Script Writing for Web Service ProtocolsThere are a few things to keep in mind if your protocol that uses a scripting component is intended to beinvoked from aWeb service interface (for example, from a web browser).

Scripting components have an advanced parameter called Check For NoUI. When set to "True", thedefault value for VBScript (on Client), the component is not invoked if the protocol is executed via theweb service interface, because the protocol has no direct user interface and the scripting component isignored. When components display a user interface (or generally require access to a client), the generalrule is to set the value to "True". However, such a scripting component protocol is not suitable forrunning 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 executionwhen this flag is set to "True".

Script Writing for Web Service Protocols | Page 27

windows scripting integration guide - Pipeline Pilot

Documents

Transcript of windows scripting integration guide - Pipeline Pilot