VWorks 14 Application Programming Interface Reference Guide
File info: application/pdf · 56 pages · 574.07KB
VWorks 14 Application Programming Interface Reference Guide
VWorks,14,Application,Programming,Interface,API,Reference,Guide,Agilent
"VWorks, 14, Application, Programming, Interface, API, Reference, Guide, Agilent"
This guide documents the interfaces exposed by VWorks software 14.0 and later. What this guide covers This guide defines the VWorks Application Programming Interface (API) methods and enumerated types required to progra…
VWorks 14 Application Programming Interface ... - Agilent
Agilent Technologies, Inc. 2021. No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation ...
regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Agilent shall not be liable for errors or for inci…
Full PDF Document
If the inline viewer fails, it will open the original document in compatibility mode automatically. You can also open the file directly.
Extracted Text
VWorks Application Programming Interface
Version 14.0
Reference Guide
Original Instructions
Notices
Manual Part Number
D0008025 Revision A
February 2021
Copyright
� Agilent Technologies, Inc. 2021
No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Agilent Technologies, Inc. as governed by United States and international copyright laws.
Contact Information
Agilent Technologies Inc. Automation Solutions 5301 Stevens Creek Blvd. Santa Clara, CA 95051 USA
Web: https://www.agilent.com
Contact page: https://www.agilent.com/en/contactus/page
Documentation feedback: documentation.automation@agilent.co m
Acknowledgements
Microsoft� and Windows� are either registered trademarks or trademarks of the Microsoft Corporation in the United States and other countries.
Warranty
The material contained in this document is provided "as is," and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Agilent disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Agilent shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Agilent and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control.
Technology Licenses
The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license.
Restricted Rights Legend
If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as "Commercial computer software" as defined in DFAR 252.227-7014 (June 1995), or as a "commercial item" as defined in FAR 2.101(a) or as "Restricted computer software" as defined in FAR 52.227-19 (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Agilent Technologies' standard commercial license terms, and non-DOD Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR 52.22719(c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR 52.227-14 (June1987) or DFAR 252.227-7015 (b)(2) (November 1995), as applicable in any technical data.
Safety Notices
WARNING
A WARNING notice denotes a haz-
ard. It calls attention to an operating procedure, practice, or the like that, if not correctly performed or adhered to, could result in personal injury or death. Do not proceed beyond a
WARNING notice until the indicated
conditions are fully understood and met.
CAUTION
A CAUTION notice denotes a hazard.
It calls attention to an operating procedure, practice, or the like that, if not correctly performed or adhered to, could result in damage to the product or loss of important data. Do not pro-
ceed beyond a CAUTION notice until
the indicated conditions are fully understood and met.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Accessing Agilent Automation Solutions user guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 AbortProtocol method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 CloseDeviceFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 CloseProtocol method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 CompileProtocol method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 GetSimulationMode method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 GetTipStates method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 LoadDeviceFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 LoadProtocol method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 LoadRunsetFile method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Login method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 LoginWithDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Logout method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 PauseProtocol method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 ReinitializeDevices method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 ResumeProtocol method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 RunProtocol method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 SetSimulationMode method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 ShowDiagsDialog method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 ShowLoginDialog method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 ShowOptionsDialog method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ShowPlateGroupEditorDialog method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ShowTipStateEditor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 ShowVWorks method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 InitializationComplete event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 LogMessage event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 MessageBoxAction event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 ProtocolAborted event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 ProtocolComplete event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 RecoverableError event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 UnrecoverableError event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 UserMessage event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
VWorks Application Programming Interface Reference Guide
iii
Contents
4. Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 V11LoginResult enumerated type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 V11ReturnCode enumerated type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
iv
VWorks Application Programming Interface Reference Guide
Preface
This preface contains the following topics: � "About this guide" on page vi � "Accessing Agilent Automation Solutions user guides" on page viii
v
Preface About this guide
About this guide
Who should read this guide
This guide is for experienced software developers and integrators who have the following requisite skills and knowledge: � Experience creating and using COM objects in any COM-enabled programming
language and implementing COM interfaces � Familiarity with VWorks software features and functions � Experience creating client applications, server applications, or both for Microsoft
Windows
Software version
This guide documents the interfaces exposed by VWorks software 14.0 and later.
What this guide covers
This guide defines the VWorks Application Programming Interface (API) methods and enumerated types required to programmatically initialize devices, run protocols, respond to errors, and monitor the status of VWorks.
This guide does not provide instructions for using the VWorks software. It is assumed that the developer is already familiar with VWorks software features and functions, including the user interface.
Table Terms used in this guide Term VWorks Automation Control VWorks Plus
VWorks Standard
Content Management (OpenLab component)
Control Panel (OpenLab component) Microsoft Control Panel
Description
VWorks software component that you use to create the protocols that run your automation devices.
Collection of software components required for running the VWorks software with compliance features. This edition includes Control Panel, Shared Services, Content Management, and Content Browser.
Collection of software components required for running the standard VWorks software. This edition includes Control Panel and Shared Services.
VWorks Plus only. The storage repository for VWorksrelated records of interest. An administrator can use the Content Browser to view the VWorks project content in Content Management.
The Shared Services user interface for configuring and managing user access and licenses.
Part of the Microsoft Windows operating system.
vi
VWorks Application Programming Interface Reference Guide
Preface About this guide
Term
Shared Services (OpenLab component)
Description
Set of administrative services that control VWorks user access and file storage. Shared Services are accessed via the Control Panel.
Related guides
For information about ... Computer requirements and installing the software
See...
VWorks Workstation Plus and VWorks Workstation Installation Guide
� Configuring the software in Control Panel, including managing licenses and user access
� Backing up and restoring the software, Shared Services database, and project content
� VWorks Automation Control Plus Administrator Guide
� VWorks Automation Control Standard Administrator Guide
Setting up a specific device and operating the device using VWorks and device diagnostics software
� VWorks Plus only. Managing audit trails and record states
� Setting up labware definitions and liquid classes � Setting up an experiment tags database and
inventory database � Migrating protocols from previous versions of
VWorks software.
Creating and running protocols.
Relevant Agilent device user guide VWorks Automation Control Setup Guide
VWorks Automation Control User Guide VWorks Quick Guide for Protocol Authors
VWorks Application Programming Interface Reference Guide
vii
Preface Accessing Agilent Automation Solutions user guides
Accessing Agilent Automation Solutions user guides
About this topic
This topic describes the different formats of user information and explains how to access it for the Agilent Automation Solutions products.
Where to find user information
The user information is available in the following locations: � Knowledge base. The help system for the Automation Solutions products is
available from: � Help menu within the VWorks software: Select Help > Knowledge Base or press
F1. � From the Windows desktop: Select Start ( ) > All Apps > Agilent
Technologies > VWorks Knowledge Base. For guidelines on using the VWorks context-sensitive help and knowledge base features, see Using the knowledge base, below. � PDF files. The PDF files of the user guides are installed with the VWorks software (C:\Program Files (x86)\Agilent Technologies\VWorks\UserGuides) and are available in the VWorks Knowledge Base. � Website. You can search the online VWorks Knowledge Base or download the latest version of any PDF file from the Agilent website at www.agilent.com/chem/askb.
Accessing safety information
Safety information for the Agilent Automation Solutions devices appears in the Automation Solutions Products General Safety Guide and in the corresponding device safety guide or user guide. You can also search the knowledge base or the PDF files for safety information.
Using the knowledge base
Knowledge base topics are displayed using web browser software such as Microsoft Edge. Note: If you want to use Internet Explorer to display the topics, you might have to allow local files to run active content (scripts and ActiveX controls). To do this, in Internet Explorer, open the Internet Options dialog box. Click the Advanced tab, locate the Security section, and select Allow active content to run in files on my computer.
viii
VWorks Application Programming Interface Reference Guide
Preface Accessing Agilent Automation Solutions user guides
Opening the help topic for an area in the VWorks window
To access the context-sensitive help feature:
1 In the main window of the VWorks software, click the help button . The pointer
changes to . Notice that the different icons or areas are highlighted as you move the pointer over them.
2 Click an icon or area of interest. The relevant topic or document opens.
VWorks Application Programming Interface Reference Guide
ix
Preface Accessing Agilent Automation Solutions user guides
Features in the Knowledge Base window
Step 1 2
3 4
5
For this task...
Contents pane. Lists all the books and the table of contents of the books.
Search. Allows you to search the Knowledge Base (all products or selected products) using keywords.
Topic area. Displays the selected online help topic.
Navigation buttons. Enable you to navigate through the next or previous topics listed in the Contents tab.
Toolbar buttons: Enable you to: � Expand or collapse all the sections in a topic that has drop-down headings. � Print the topic. � Send feedback by email for a given topic.
x
VWorks Application Programming Interface Reference Guide
1 Introduction
Interface name IVWorks4API
_IVWorks4APIEvent
VWorks software includes optional features that allow customers to extend its core functionality to meet specific process or application needs.
The VWorks Application Programming Interface is an optional feature of VWorks software that developers can use to write their own applications to control VWorks software programmatically.
This guide defines the interfaces and enumerations provided for developing applications that control VWorks software using the VWorks Component Object Model (COM) Application Programming Interface (API).
The following interfaces are included in the COM implementation:
Purpose
Type library
The IVWorksAPI interface is used by an application to control VWorks software programmatically.
IVWorks4API interface member methods are defined in "Methods" on page 3.
Works.exe
The _IVWorks4APIEvent interface designates an event sink interface that an application must implement to receive event notifications from VWorks software.
_IVWorks4APIEvent interface member events are defined in "Events" on page 33.
Works.exe
1
1 Introduction This page is intentionally blank.
2
VWorks Application Programming Interface Reference Guide
2 Methods
The methods defined in this section are members of the IVWorks4API interface, which is included in the VWorks COM implementation.
You can use the following table to quickly locate a VWorks Application Programming Interface method by name, by description, or by page number.
Method AbortProtocol CloseDeviceFile CloseProtocol CompileProtocol EnumerateUsers
GetSimulationMode GetTipStates
LoadDeviceFile LoadProtocol LoadRunsetFile Login
LoginWithDomain
Description
See...
Aborts the protocol run that is in "AbortProtocol method" on
progress.
page 5
Closes the specified device file. "CloseDeviceFile" on page 6
Closes the specified protocol file.
"CloseProtocol method" on page 7
Compiles the specified protocol. "CompileProtocol method" on page 8
This method has been
NA
deprecated and is no longer
used.
Gets the simulation mode state. "GetSimulationMode method" on page 10
Gets the state of the tip boxes in "GetTipStates method" on
the specified protocol for
page 11
automated tip tracking.
Loads the specified device file. "LoadDeviceFile" on page 14
Loads the specified protocol for "LoadProtocol method" on
a run.
page 15
Loads the specified runset file. "LoadRunsetFile method" on page 17
Logs in to VWorks using the specified user name and password.
"Login method" on page 18
Logs in to VWorks using the specified user name, password and Domain. This method is available when Windows Domain authentication is configured in the OpenLab Control Panel.
"LoginWithDomain" on page 19
3
2 Methods
Method Logout PauseProtocol ReinitializeDevices ResumeProtocol RunProtocol SetSimulationMode ShowDiagsDialog
ShowLoginDialog ShowManageUserDialog
ShowOptionsDialog ShowPlateGroupEditorDialog ShowTipStateEditor ShowVWorks
Description
See...
Ends the current user session when the user logs out.
"Logout method" on page 20
Pauses the protocol run that is "PauseProtocol method" on
in progress.
page 21
Reinitializes all devices in the active device file.
"ReinitializeDevices method" on page 22
Resumes the protocol run.
"ResumeProtocol method" on page 23
Runs the specified protocol the "RunProtocol method" on
specified number of times.
page 24
Turns simulation mode on or off.
"SetSimulationMode method" on page 26
Displays the Diagnostics window, which contains a list of active devices. The user can select a device from the list and then click a button to display the device diagnostics dialog box.
"ShowDiagsDialog method" on page 27
Displays the User Authentication "ShowLoginDialog method" on
(login) dialog box.
page 28
This method has been
NA
deprecated and is no longer
used.
Displays the Options dialog box. "ShowOptionsDialog method" on page 29
Displays the Plate Groups tab in "ShowPlateGroupEditorDialog
the Inventory Editor.
method" on page 30
Displays the Tip State Editor dialog box.
"ShowTipStateEditor method" on page 31
Displays or hides the VWorks main window.
"ShowVWorks method" on page 32
4
VWorks Application Programming Interface Reference Guide
AbortProtocol method
2 Methods AbortProtocol method
Description Syntax
Aborts the protocol run that is in progress.
HRESULT AbortProtocol( [out,retval] enum V11ReturnCode* returnCode);
Return value
The AbortProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM->AbortProtocol();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.AbortProtocol()
Related information
For information about... CloseProtocol method CompileProtocol method LoadProtocol method PauseProtocol method ProtocolAborted event ResumeProtocol method RunProtocol method
See... "CloseProtocol method" on page 7 "CompileProtocol method" on page 8 "LoadProtocol method" on page 15 "PauseProtocol method" on page 21 "ProtocolAborted event" on page 38 "ResumeProtocol method" on page 23 "RunProtocol method" on page 24
VWorks Application Programming Interface Reference Guide
5
2 Methods CloseDeviceFile
CloseDeviceFile
Description Syntax
Closes the specified device file.
HRESULT CloseDeviceFile([in] BSTR deviceFile, [out, retval] enum V11ReturnCode* returnCode);
Parameters
device file
[in] The path of the device file to close.
The device file (.dev) must be in the OpenLab Shared Services storage.
Return value
The CloseDeviceFile method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM-> CloseDeviceFile("VWorks Projects/VWorks/ General/Devices/My Device File 1.dev");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.CloseDeviceFile ("VWorks Projects/VWorks/ General/Devices/My Device File 1.dev");
Related information
For information about... LoadDeviceFile
See... "LoadDeviceFile" on page 14
6
VWorks Application Programming Interface Reference Guide
CloseProtocol method
2 Methods CloseProtocol method
Description Syntax
Closes the specified protocol file.
HRESULT CloseProtocol( [in] BSTR protocol, [out,retval] enum V11ReturnCode* returnCode;
Parameters
protocol
[in] The file path of the protocol.
The protocol file (.pro) must be in the OpenLab Shared Services storage.
Return value
The CloseProtocol function method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM->CloseProtocol("VWorks Projects/VWorks/ General/Protocols/My Protocol File 1.pro");
Visual Basic .NET
Dim vwRetCode As VWorks4Lib.V11ReturnCode vwRetCode = oVWorksCOM.CloseProtocol("VWorks Projects/VWorks/ General/Protocols/My Protocol File 1.pro")
Related information
For information about... AbortProtocol method CompileProtocol method LoadProtocol method
See... "AbortProtocol method" on page 5 "CompileProtocol method" on page 8 "LoadProtocol method" on page 15
VWorks Application Programming Interface Reference Guide
7
2 Methods CompileProtocol method
For information about... PauseProtocol method ResumeProtocol method RunProtocol method
See... "PauseProtocol method" on page 21 "ResumeProtocol method" on page 23 "RunProtocol method" on page 24
CompileProtocol method
Description Syntax
Compiles the specified protocol. This method is used with the LogMessage event. See "LogMessage event" on page 35.
HRESULT CompileProtocol( [in] BSTR protocol, [out] LONG* errorCount, [out] LONG* warningCount, [out,retval] enum V11ReturnCode* returnCode);
Parameters
protocol errorCount warningCount
[in] The file path of the protocol. The protocol file (.pro) must be in the OpenLab Shared Services storage.
[out] Pointer to a variable that receives the number of errors found.
[out] Pointer to a variable that receives the number of warnings found.
Return value
The CompileProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
8
VWorks Application Programming Interface Reference Guide
2 Methods CompileProtocol method
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; LONG errCount, wrnCount; retCode = oVWorksCOM->CompileProtocol ("VWorks Projects/VWorks/General/Protocols/My Protocol File 1.pro", &errCount, &wrnCount);
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode Dim errCount, wrnCount as Long retCode = oVWorksCOM.CompileProtocol ("VWorks Projects/VWorks/General/Protocols/My Protocol File 1.pro", errCount, wrnCount)
Related information
For information about... AbortProtocol method CloseProtocol method LoadProtocol method LogMessage event PauseProtocol method ResumeProtocol method RunProtocol method
See... "AbortProtocol method" on page 5 "CloseProtocol method" on page 7 "LoadProtocol method" on page 15 "LogMessage event" on page 35 "PauseProtocol method" on page 21 "ResumeProtocol method" on page 23 "RunProtocol method" on page 24
VWorks Application Programming Interface Reference Guide
9
2 Methods GetSimulationMode method
GetSimulationMode method
Description Syntax
Gets the simulation mode state.
HRESULT GetSimulationMode( [out, retval] VARIANT_BOOL *mode);
Parameters
None.
Return value
The GetSimulationMode method returns the simulation mode state. Possible values: TRUE = Simulation mode is on FALSE = Simulation mode is off
Sample code
Visual C++
VARIANT_BOOL bSimMode; bSimMode= oVWorksCOM->GetSimulationMode();
Visual Basic .NET
Dim bSimMode as Boolean bSimMode= oVWorksCOM.GetSimulationMode()
Related information
For information about... SetSimulationMode method
See... "SetSimulationMode method" on page 26
10
VWorks Application Programming Interface Reference Guide
GetTipStates method
2 Methods GetTipStates method
Description Syntax
Gets the state of the tip boxes in the specified protocol for automated tip tracking.
HRESULT GetTipStates( [in] BSTR protocol, [out] BSTR* TipStateXML, [out,retval] enum V11ReturnCode* returnCode);
Parameters
protocol TipStateXML
[in] The file path of the protocol.
The protocol file (.pro) must be in the OpenLab Shared Services storage.
[out] Pointer to a variable that receives the current status of the tipboxes.
GetTipStates method output
The GetTipStates method returns an XML metadata string in the TipStateXML parameter.
XML structure
<Velocity11> <AllTipBoxStateQuery> <TipBoxStateQuery> <SingleTipBoxStateQuery> <TipBoxState> <PipetteHeadMode /> <TipPositions> <TipPosition State='0' > <Wells > <Well /> ... </Wells> </TipPosition> <TipPosition /> </TipPositions> </TipBoxState> </SingleTipBoxStateQuery> </TipBoxStateQuery> </AllTipBoxStateQuery>
</Velocity11>
VWorks Application Programming Interface Reference Guide
11
2 Methods GetTipStates method
XML elements and attributes
The elements and attributes of interest to this method are described in this section. Velocity11 is the root element, and all other elements except PipetteHeadMode are container elements.
SingleTipBoxStateQuery element
The SingleTipBoxStateQuery element has the following attributes:
Attribute name InstanceOrLocationName
ProcessLabware
ProcessOrDeviceName
Value
For process labware, the value is the labware instance of the tipbox.
For configured labware, the value is the name of the location on the device where the tipbox has been placed.
Indicates the type of labware.
Possible value:
0 = The tip box is configured labware
1 = The tip box is process labware
For process labware, the value is the name of the process by which the tip box enters the system.
For configured labware, the value is the name of the device on which the tip box has been placed.
TipBoxState element
The TipBoxState element has the following attribute:
Attribute name NumWells
Description The number of wells (tips) in the tipbox.
TipPosition element
The TipPosition element has the following attribute:
Attribute name State
Description
Indicates whether the tips have been used. Possible values: 0 = The tips have not been used 1 = The tips have been used
Well element
The Well element has the following attributes:
12
VWorks Application Programming Interface Reference Guide
2 Methods GetTipStates method
Attribute name Column
Row
Description
The column index of the tip, where 0 indicates the leftmost column.
The row index of the tip, where 0 indicates the topmost row.
Example of GetTipStates method output
The following sample code is a truncated example of an XML metadata string that is returned by the GetTipStates method in the TipStateXML parameter. In this example, the tip box contains only unused tips. The wells listed under <TipPosition State='0'> contain tips that have not been used. The wells listed under <TipPosition State='1'> contain tips that have been used.
<Velocity11 file='MetaData' md5sum='50a7e93353a1993ae7a53db21dd3a948' version='1.0' > <AllTipBoxStateQuery > <TipBoxStateQuery > <SingleTipBoxStateQuery InstanceOrLocationName='1' ProcessLabware='0'
<rarr RightArrow>�ProcessOrDeviceName='Bravo - 1' > <TipBoxState NumWells='384' > <PipetteHeadMode Channels='1' ColumnCount='1' RowCount='1'
<rarr RightArrow>�SubsetConfig='0' SubsetType='4' TipType='0' /> <TipPositions > <TipPosition State='0' > <Wells > <Well Column='0' Row='0' /> <Well Column='1' Row='0' />
... <Well Column='22' Row='15' /> <Well Column='23' Row='15' />
</Wells> </TipPosition> <TipPosition State='1' /> </TipPositions> </TipBoxState> </SingleTipBoxStateQuery> </TipBoxStateQuery> </AllTipBoxStateQuery> </Velocity11>
Return value
The GetTipStates method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual Basic .NET
Dim TipStateXML As String = "" Dim retCode As VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.GetTipStates("VWorks Projects/VWorks/General/Protocols/My Protocol File 1.pro", TipStateXML)
VWorks Application Programming Interface Reference Guide
13
2 Methods LoadDeviceFile
LoadDeviceFile
Description Syntax
Loads the specified device file.
HRESULT LoadDeviceFile([in] BSTR deviceFile, [out, retval] enum V11ReturnCode* returnCode);
Parameters
device file
[in] The path of the device file to load.
The device file (.dev) must be in the OpenLab Shared Services storage.
Return value
The LoadDeviceFile method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM-> LoadDeviceFile("VWorks Projects/VWorks/ General/Devices/My Device File 1.dev");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.LoadDeviceFile ("VWorks Projects/VWorks/ General/Devices/My Device File 1.dev");
Related information
For information about... CloseDeviceFile
See... "CloseDeviceFile" on page 6
14
VWorks Application Programming Interface Reference Guide
LoadProtocol method
2 Methods LoadProtocol method
Description Syntax
Loads the specified protocol for a run.
HRESULT LoadProtocol( [in] BSTR protocol, [out,retval] enum V11ReturnCode* returnCode);
Parameters
protocol
[in] The file path of the protocol.
The protocol file (.pro) must be in the OpenLab Shared Services storage.
Return value
The LoadProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->LoadProtocol("VWorks Projects/VWorks/General/ Protocols/My Protocol File 1.pro");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.LoadProtocol ("VWorks Projects/VWorks/General/ Protocols/My Protocol File 1.pro")
Related information
For information about... AbortProtocol method CloseProtocol method CompileProtocol event
See... "AbortProtocol method" on page 5 "CloseProtocol method" on page 7 "CompileProtocol method" on page 8
VWorks Application Programming Interface Reference Guide
15
2 Methods LoadProtocol method
For information about... PauseProtocol method ResumeProtocol method RunProtocol method
See... "PauseProtocol method" on page 21 "ResumeProtocol method" on page 23 "RunProtocol method" on page 24
16
VWorks Application Programming Interface Reference Guide
LoadRunsetFile method
2 Methods LoadRunsetFile method
Description Syntax
Loads the specified runset file.
HRESULT LoadRunsetFile( [in] BSTR runset, [out,retval] enum V11ReturnCode* returnCode);
Parameters
runset
[in] The file path of the runset.
The runset file (.rst) must be in the OpenLab Shared Services storage.
Return value
The LoadRunsetFile method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->LoadRunsetFile ("VWorks Projects/VWorks/ General/Runsets/My Runset File 1.rst");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.LoadRunsetFile ("VWorks Projects/VWorks/ General/Runsets/My Runset File 1.rst")
VWorks Application Programming Interface Reference Guide
17
2 Methods Login method
Login method
Description Syntax
Logs the specified user in to VWorks using the specified user name and password.
HRESULT Login( [in] BSTR userName, [in] BSTR password, [out,retval] enum V11LoginResult* loginResult);
Parameters
These parameters are for a user account that has been created or configured in OpenLab Control Panel.
userName password
[in] The name of the user. [in] The user's password.
Returns
The Login method returns the login status of type V11LoginResult. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11LoginResult retCode; loginResult= oVWorksCOM->Login("user1","mypassword!");
Visual Basic .NET
Dim loginResult as VWorks4Lib.V11LoginResult loginResult= oVWorksCOM.Login("user1","mypassword!")
Related information
For information about... Logout method ShowLoginDialog method
See... "Logout method" on page 20 "ShowLoginDialog method" on page 28
18
VWorks Application Programming Interface Reference Guide
LoginWithDomain
2 Methods LoginWithDomain
Description Syntax
Logs in to VWorks using the specified user name, password and Domain. This method is available when Windows Domain authentication is configured in the OpenLab Control Panel.
HRESULT LoginWithDomain ([in] BSTR userName, [in] BSTR password , [in] BSTR domain , [out, retval] enum V11ReturnCode* returnCode);
Parameters
userName password domain
The name of the user to log-in. The password for the user account. The domain name to be used for authentication.
Return value
The LoginWithDomain method returns the login status of type V11LoginResult. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM-> LoginWithDomain("user1", "mypassword!", "Agilent");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.LoginWithDomain("user1", "mypassword!", "Agilent");
Related information
For information about... Logout method ShowLoginDialog method
See... "Logout method" on page 20 "ShowLoginDialog method" on page 28
VWorks Application Programming Interface Reference Guide
19
2 Methods Logout method
Logout method
Description Syntax
Ends the current user session when the user logs out.
HRESULT Logout( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The Logout method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM->Logout();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.Logout()
Related information
For information about... Login method ShowLoginDialog method
See... "Login method" on page 18 "ShowLoginDialog method" on page 28
20
VWorks Application Programming Interface Reference Guide
PauseProtocol method
2 Methods PauseProtocol method
Description Syntax
Pauses the protocol run that is in progress.
HRESULT PauseProtocol( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The PauseProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM->PauseProtocol();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode = oVWorksCOM.PauseProtocol()
Related information
For information about... AbortProtocol method CloseProtocol method CompileProtocol method LoadProtocol method ResumeProtocol method RunProtocol method
See... "AbortProtocol method" on page 5 "CloseProtocol method" on page 7 "CompileProtocol method" on page 8 "LoadProtocol method" on page 15 "ResumeProtocol method" on page 23 "RunProtocol method" on page 24
VWorks Application Programming Interface Reference Guide
21
2 Methods ReinitializeDevices method
ReinitializeDevices method
Description Syntax
Reinitializes all devices in the active device file.
HRESULT ReinitializeDevices( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ReinitializeDevices method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ReinitializeDevices();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ReinitializeDevices()
Related information
For information about... InitializationComplete event
See... "InitializationComplete event" on page 34
22
VWorks Application Programming Interface Reference Guide
ResumeProtocol method
2 Methods ResumeProtocol method
Description Syntax
Resumes the protocol run.
HRESULT ResumeProtocol( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ResumeProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM->ResumeProtocol();
Visual Basic .NET
VWorks4Lib.V11ReturnCode retCode; retCode = oVWorksCOM.ResumeProtocol();
Related information
For information about... AbortProtocol method CloseProtocol method CompileProtocol method LoadProtocol method PauseProtocol method RunProtocol method
See... "AbortProtocol method" on page 5 "CloseProtocol method" on page 7 "CompileProtocol method" on page 8 "LoadProtocol method" on page 15 "PauseProtocol method" on page 21 "RunProtocol method" on page 24
VWorks Application Programming Interface Reference Guide
23
2 Methods RunProtocol method
RunProtocol method
Description Syntax
Runs the specified protocol the specified number of times.
HRESULT RunProtocol( [in] BSTR protocol, [in] LONG runCount, [out,retval] enum V11ReturnCode* returnCode);
Parameters
protocol
runCount
[in] The file path of the protocol. The protocol file (.pro) must be in the OpenLab Shared Services storage.
[in] The number of times to run the protocol.
Return value
The RunProtocol method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->RunProtocol ("VWorks Projects/VWorks/General/ Protocols/My Protocol File 1.pro",2);
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.RunProtocol ("VWorks Projects/VWorks/General/ Protocols/My Protocol File 1.pro",2)
24
VWorks Application Programming Interface Reference Guide
Related information
For information about... AbortProtocol method CloseProtocol method CompileProtocol method LoadProtocol method PauseProtocol method ResumeProtocol method
2 Methods RunProtocol method
See... "AbortProtocol method" on page 5 "CloseProtocol method" on page 7 "CompileProtocol method" on page 8 "LoadProtocol method" on page 15 "PauseProtocol method" on page 21 "ResumeProtocol method" on page 23
VWorks Application Programming Interface Reference Guide
25
2 Methods SetSimulationMode method
SetSimulationMode method
Description Syntax
Turns simulation mode on or off.
HRESULT SetSimulationMode( [in] VARIANT_BOOL mode, [out, retval] enum V11ReturnCode* returnCode);
Parameters
mode
[in] The simulation mode state to set. Possible values: TRUE = Turn on simulation mode FALSE = Turn off simulation mode
Return value
The SetSimulationMode method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCod retCode; retCode = oVWorksCOM->SetSimulationMode(VARIANT_TRUE); retCode = oVWorksCOM->SetSimulationMode(VARIANT_FALSE);
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.SetSimulationMode(True) retCode=oVWorksCOM.SetSimulationMode(False)
Related information
For information about... GetSimulationMode method
See... "GetSimulationMode method" on page 10
26
VWorks Application Programming Interface Reference Guide
ShowDiagsDialog method
2 Methods ShowDiagsDialog method
Description Syntax
Displays the Diagnostics window in front of the VWorks main window. In this window, the user can select a device from the list of active devices and then click the Device diagnostics button to display the device's diagnostics dialog box.
HRESULT ShowDiagsDialog( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ShowDiagsDialog method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowDiagsDialog();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowDiagsDialog()
VWorks Application Programming Interface Reference Guide
27
2 Methods ShowLoginDialog method
ShowLoginDialog method
Description Syntax
Displays the User Authentication (login) dialog box.
HRESULT ShowLoginDialog( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ShowLoginDialog method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowLoginDialog();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowLoginDialog()
Related information
For information about... Login method Logout method
See... "Login method" on page 18 "Logout method" on page 20
28
VWorks Application Programming Interface Reference Guide
ShowOptionsDialog method
2 Methods ShowOptionsDialog method
Description Syntax
Displays the Options dialog box.
HRESULT ShowOptionsDialog( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ShowOptionsDialog method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowOptionsDialog();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowOptionsDialog()
VWorks Application Programming Interface Reference Guide
29
2 Methods ShowPlateGroupEditorDialog method
ShowPlateGroupEditorDialog method
Description Syntax
Displays the Plate Groups tab in the Inventory Editor.
HRESULT ShowPlateGroupEditorDialog( [out,retval] enum V11ReturnCode* returnCode);
Parameters
None.
Return value
The ShowPlateGroupEditorDialog method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowPlateGroupEditorDialog();
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowPlateGroupEditorDialog()
30
VWorks Application Programming Interface Reference Guide
ShowTipStateEditor method
2 Methods ShowTipStateEditor method
Description Syntax
Displays the Tip State Editor.
HRESULT ShowTipStateEditor( [in] BSTR protocol, [out,retval] enum V11ReturnCode* returnCode);
Parameters
protocol
[in] The file path of the protocol.
The protocol file (.pro) must be in the OpenLab Shared Services storage.
Return value
The ShowTipStateEditor method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowTipStateEditor ("VWorks Projects/VWorks/ General/Protocols/My Protocol File 1.pro");
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowTipStateEditor ("VWorks Projects/VWorks/ General/Protocols/My Protocol File 1.pro")
Related information
For information about... GetTipStates method
See... "GetTipStates method" on page 11
VWorks Application Programming Interface Reference Guide
31
2 Methods ShowVWorks method
ShowVWorks method
Description Syntax
Displays or hides the VWorks main window.
HRESULT ShowVWorks( [in] VARIANT_BOOL showOrHide, [out, retval] enum V11ReturnCode* returnCode);
Parameters
showOrHide
[in] Indicates whether to display or hide the VWorks main window.
Possible values:
TRUE = Display the VWorks main window
FALSE = Hide the VWorks main window
Return value
The ShowVWorks method returns the method-call status of type V11ReturnCode. For possible values, see "V11ReturnCode enumerated type" on page 45.
Sample code
Visual C++
VWorks4Lib.V11ReturnCode retCode; retCode=oVWorksCOM->ShowVWorks (VARIANT_TRUE);
Visual Basic .NET
Dim retCode as VWorks4Lib.V11ReturnCode retCode=oVWorksCOM.ShowVWorks (True)
32
VWorks Application Programming Interface Reference Guide
3 Events
The events defined in this chapter are members of the _IVWorks4APIEvent interface, which is included in the VWorks COM implementation. To receive event notifications from a VWorks object, an automation client must implement this interface.
You can use the following table to quickly locate a VWorks Application Programming Interface event by name, by description, or by page number.
Event InitializationComplete LogMessage MessageBoxAction ProtocolAborted
ProtocolComplete
RecoverableError
UnrecoverableError UserMessage
Description
See...
Fires when the device initialization is "InitializationComplete event"
finished.
on page 34
Fires when a message is posted to the "LogMessage event" on
Main Log.
page 35
Fires when a user response is required.
"MessageBoxAction event" on page 36
Fires when the operator or automation client aborts the protocol run.
"ProtocolAborted event" on page 38
Fires after the Startup Protocol, Cleanup Protocol, or Main Protocol is finished.
"ProtocolComplete event" on page 39
Fires when an error occurs to which "RecoverableError event" on the user can respond with abort, retry, page 40 or ignore.
Fires when an error occurs to which no user response is required.
"UnrecoverableError event" on page 41
Fires when a User Message task occurs.
"UserMessage event" on page 42
33
3 Events InitializationComplete event
InitializationComplete event
Description Syntax
Fires when device initialization is finished.
void InitializationComplete( [in] LONG session
);
Parameters
session
[in] The session ID.
Related information
For information about... ReinitializeDevices method
See...
"ReinitializeDevices method" on page 22
34
VWorks Application Programming Interface Reference Guide
LogMessage event
3 Events LogMessage event
Description Syntax
Fires when a message is posted to the Main Log.
HRESULT LogMessage( [in] LONG session, [in] LONG logClass, [in] BSTR timeStamp, [in] BSTR device, [in] BSTR location, [in] BSTR process, [in] BSTR task, [in] BSTR fileName, [in] BSTR message
);
Parameters
session logClass
timeStamp device location process task fileName message
[in] The session ID.
[in] A value that represents the message type. Possible values: 0 = Info 1 = Warning 2 = Error 3 = Event 4 = PipetteTransfer 5 = Script 6 = UserDefined
[in] The time at which the event occurred.
[in] The device name, or an empty string.
[in] The location, or an empty string.
[in] The labware name, or an empty string.
[in] The task name, or an empty string.
[in] The protocol file name, the device file name, or an empty string.
[in] The text that describes the error.
VWorks Application Programming Interface Reference Guide
35
3 Events MessageBoxAction event
Related information
For information about... CompileProtocol method
See... "CompileProtocol method" on page 8
MessageBoxAction event
Description Syntax
Fires when a user response is required.
HRESULT MessageBoxAction( [in] LONG session, [in]LONG type, [in] BSTR message, [in] BSTR caption, [out] LONG* actionToTake
);
Parameters
session type
message caption
[in] The session ID.
[in] A value that represents the message-box type. Possible values: 0 = The message box contains one push button: OK (MB_OK) 1 = The message box contains three push buttons: Yes, No, and Cancel (MB_OKCANCEL) 2 = The message box contains three push buttons: Abort, Retry, and Ignore (MB_ABORTRETRYIGNORE) 3 = The message box contains three push buttons: Yes, No, and Cancel (MB_YESNOCANCEL) 4 = The message box contains two push buttons: Yes and No (MB_YESNO) 5 = The message box contains two push buttons: Retry and Cancel (MB_RETRYCANCEL)
[in] The message text.
[in] The title bar text.
36
VWorks Application Programming Interface Reference Guide
3 Events MessageBoxAction event
actionToTake
[out] Pointer to a variable that receives a value that represents the action to take. Possible values: 1 = OK 2 = CANCEL 3 = ABORT 4 = RETRY 5 = IGNORE 6 = YES 7 = NO
VWorks Application Programming Interface Reference Guide
37
3 Events ProtocolAborted event
ProtocolAborted event
Description Syntax
Fires when the operator or automation client aborts the protocol run.
HRESULT ProtocolAborted( [in] LONG session, [in] BSTR protocol, [in] BSTR protocol_type
);
Parameters
session protocol protocol_type
[in] The session ID.
[in] The file path of the protocol.
[in] A value that represents the protocol type. Possible values: � Startup � Main � Cleanup
Related information
For information about... AbortProtocol method
See... "AbortProtocol method" on page 5
38
VWorks Application Programming Interface Reference Guide
ProtocolComplete event
3 Events ProtocolComplete event
Description Syntax
Fires after each of the following protocols is finished: � Startup Protocol � Cleanup Protocol � Main Protocol
HRESULT ProtocolComplete( [in] LONG session, [in] BSTR protocol, [in] BSTR protocol_type
);
Parameters
session protocol protocol_type
[in] The session ID.
[in] The file path of the protocol.
[in] A value that represents the protocol type. Possible values: � Startup � Main � Cleanup
VWorks Application Programming Interface Reference Guide
39
3 Events RecoverableError event
RecoverableError event
Description Syntax
Fires whenever an error occurs to which the user can respond with abort, retry, or ignore.
HRESULT RecoverableError( [in] LONG session, [in] BSTR device, [in] BSTR location, [in] BSTR description, [out] LONG* actionToTake, [out] VARIANT_BOOL* vworksHandlesError
);
Parameters
session device location description actionToTake
vworksHandlesError
[in] The session ID.
[in] The name of the device on which the error occurred, or an empty string.
[in] The location on the device where the error occurred, or an empty string.
[in] The text that describes the error.
[out] Pointer to a variable that receives a value that represents the action to take. Possible values: 0 = Abort 1 = Retry 2 = Ignore
[out] A variable that receives a value that indicates whether VWorks software should handle the error. Possible values: TRUE = Allow VWorks software to handle the error FALSE = Do not allow VWorks software to handle the error
40
VWorks Application Programming Interface Reference Guide
Related information
For information about... UnrecoverableError event
3 Events UnrecoverableError event
See... "UnrecoverableError event" on page 41
UnrecoverableError event
Description Syntax
Fires when an error occurs to which no user response is required.
HRESULT UnrecoverableError( [in] LONG session, [in] BSTR description
);
Parameters
session description
[in] The session ID. [in] The message text.
Related information
For information about... RecoverableError event
See... "RecoverableError event" on page 40
VWorks Application Programming Interface Reference Guide
41
3 Events UserMessage event
UserMessage event
Description Syntax
Fires when a User Message task occurs.
HRESULT UserMessage( [in] LONG session, [in] BSTR caption, [in] BSTR message, [in] VARIANT_BOOL wantsData, [out] BSTR* userData
);
Parameters
session caption message wantsData
userData
[in] The session ID.
[in] The title bar text.
[in] The message (body) text.
[in] A value that indicates whether data can be returned in the userData parameter to update a JavaScript variable specified in the User Message task. Possible values: TRUE = Data can be returned FALSE = Data cannot be returned
[out] Pointer to a variable that receives the variable value. The value of the wantsData parameter must be TRUE. The data returned is used to set the JavaScript variable specified in the User Message task.
42
VWorks Application Programming Interface Reference Guide
4 Enumerations
This chapter defines the enumerated types used in VWorks Application Programming Interface methods. This chapter contains the following topics: � "V11LoginResult enumerated type" on page 44 � "V11ReturnCode enumerated type" on page 45
43
4 Enumerations V11LoginResult enumerated type
V11LoginResult enumerated type
Description Syntax
Indicates the login status.
enum V11LoginResult { LOGIN_SUCCESS = 0, LOGIN_FAIL = 1, LOGIN_DISABLED = 2, LOGIN_EXPIRED = 3, LOGIN_TOO_MANY_FAILED_ATTEMPTS = 4, LOGIN_NOT_ENOUGH_AUTHORIZATION = 5,
};
Constants
Name LOGIN_SUCCESS LOGIN_FAIL LOGIN_DISABLED LOGIN_EXPIRED LOGIN_TOO_MANY_FAILED_ATTEMPTS LOGIN_NOT_ENOUGH_AUTHORIZATION
Value Description
0
The login succeeded.
1
The login failed.
2
The login was disabled.
3
The login period passed.
4
Too many login attempts were made and failed.
5
Higher access privileges are required to perform the
requested action.
44
VWorks Application Programming Interface Reference Guide
V11ReturnCode enumerated type
4 Enumerations V11ReturnCode enumerated type
Description Syntax
Indicates the method-call status.
enum V11ReturnCode { RETURN_SUCCESS = 0, RETURN_BAD_ARGS = 1, RETURN_FAIL = 2,
};
Constants
Name RETURN_SUCCESS RETURN_BAD_ARGS RETURN_FAIL
Value Description
0
The method-call succeeded.
1
The method returned bad arguments.
2
The method-call failed.
VWorks Application Programming Interface Reference Guide
45
www.agilent.com � Agilent Technologies, Inc. 2021
Febrauary 2021
*D0008025*
D0008025 Revision A