VWorks Software User Guide : Creating a protocol: advanced topics : VWorks-defined functions
VWorks-defined functions
The VWorks JavaScript interpreter supports the JavaScript 1.5 or later core functions and objects. VWorks also has its own functions and objects that can be used.
The following VWorks-defined functions are available globally, so they are not restricted to a particular object or programming context.
 
Function
Description
DisplayAsyncMessageBox().
Designed to be called from a script that is run from a button on a form. For details, see Opening a message from a form button using JavaScript.
DownloadFromStorage()
Downloads a file from Shared Services (OLSS) storage to a specified Windows file path. Writes a JavaScript error message to the Main log if the download fails.
Files that are created external to the VWorks software, for example, .xlsm files, cannot be run directly from OLSS storage. However, you can create a script using DownloadFromStorage() to download the file from OLSS storage to the local file system, ShellExecute() to run the downloaded file, and UploadToStorage() to upload the file again to OLSS storage.
Parameters:
1 Text string. Shared Services file path to the file name to be downloaded, where the file path
• May or may not begin with "[olssvr]:".
• Must be relative to the Shared Services root directory for the software edition:
"[olssvr]:VWorks Projects/VWorks/
Note: An extra / or \ at the beginning of the path or after [olssvr]: is ignored.
2 Text string. Windows file path to the directory where the file is to be downloaded.
The file will be downloaded with the same file name that it has in Shared Services storage.
Examples:
DownloadFromStorage("[olssvr]:VWorks Projects/VWorks/Workstation/Barcodes/MyBarcodes.csv","C:/temp/Myfiles/")
DownloadFromStorage("[olssvr]:VWorks Projects/VWorks/Miscellaneous/Scripts/Serial Dilution Method Setup Tool.xlsm","C:\\Temp");
ShellExecute("C:\\Temp\\Serial Dilution Method Setup Tool.xlsm","",true);
UploadToStorage ("C:\\Temp\\Serial_Dilution_Method_File.csv","[olssvr]:VWorks Projects/VWorks/Workstation/Hitpick Input Files/");
GetGlobalObject()
Provides the ability to get the global context from a JavaScript that is executed in a context other than the global context. Returns an object that has all the variables of the global context. For example, in a protocol that uses the local context for variables, you can have a JavaScript task that includes a variable in the global context.
Example:
//(0) Create a reference to global object from this context.
var g_ref = GetGlobalObject();
//(1) Declare a var xx in GlobalObject.
g_ref.xx = 4
//(2) Increment the variable.
g_ref.xx++
//(3) Print the variable.
print(g_ref.xx)
Note: In this example, lines (2) and (3) could be executing from different protocols, each in their own private context, with shared data results.
Note: You can set a breakpoint on the task that uses this function to open the Debugger dialog box and view the variable (g_ref). For details on setting breakpoints, see Using breakpoints to monitor and troubleshoot tasks.
IsCompliantMode()
Returns a Boolean:
• If true, VWorks is running in Compliance mode (compliance-enabled edition).
• If false, VWorks is running in Non-Compliance mode (Standard edition).
Example:
var isCompliant = IsCompliantMode();
if (isCompliant)
print ("Running in Compliant mode");
else
print ("Not running in Compliant mode");
open()
Opens a text file and immediately executes the file contents as script.
Parameter: Text string
Make sure the file is in ANSI text format. The file extension is not important.
Note: Microsoft Notepad saves in ANSI text format by default.
Examples (local file system):
open("c:\\VWorks workspace\\script.js")
open("c:\\VWorks workspace\\script.txt")
Example (Shared Services storage):
open("[olssvr]:VWorks Projects/VWorks/Miscellaneous/Scripts/script.js")
Note: You can import JavaScript (.js) and text (.txt) files into Shared Services storage using the VWorks File > Import Misc command.
print()
Prints time-stamped messages to the VWorks log.
Parameter: Text string
Example: print(plate.name)
run()
Runs a Microsoft Windows script as though it is being called from a command line.
Note: The run() function cannot invoke Microsoft Excel if passed the name of an .xlsx file.
Writes a JavaScript error message to the log if the operation fails.
Parameters:
• Text string. Required. Allows you to initiate a command that you could otherwise enter into the Windows Run dialog box, such as notepad text.txt (opens a file named text.txt in Windows Notepad).
• Boolean true/false. Optional.
– False. (Default) The software does not wait for the function to complete before continuing.
– True. The software waits for the function to complete before continuing (blocking).
Examples:
run("notepad")
run("notepad",true)
The first example starts Notepad. The second example starts Notepad and pauses the VWorks software until you exit Notepad.
Note: A batch file (.bat) can be run only if it resides on the local disk.
ShellExecute()
Runs an executable (.exe) or opens a document file as though being called from a Windows command line.
Writes a JavaScript error message to the log if the attempt to execute fails.
Use ShellExecute() instead of run() to execute a document by having Windows launch the application associated with that document type. For example, you could use this function to launch Microsoft Excel (if installed) and load an .xlsx file.
Note: To launch an app with explicit command-line arguments, they need to be passed in separately as the (optional) second argument to the function.
Parameters:
• Text string. Required. The name of the file to be executed (.exe or document). If the string specifies
– An .exe file, it executes as if the file name had been passed to run().
– A file with an associated application, for example an .xlsx file on a computer where Microsoft Excel is installed, the function launches the application with the file name passed in as the document to open.
• Text string. Optional. Any command-line arguments to be passed in.
• Boolean true/false. Optional.
– True. The software waits for the spawned process to finish before continuing (blocking).
– False. The software does not wait for the spawned process to finish before continuing.
• Integer. Optional. If this parameter is present, the app will be launched as follows, depending on the value of the integer. Use one of the following values:
– 3, the app will start out maximized, if it is capable of being maximized.
– 1 or 5, the app will start out in a normal, not-minimized state, if it is capable of displaying a top-level window.
– 6, the app will start out minimized, as though this parameter were absent.
Other values give undefined behavior, but do not generate errors or warnings.
Examples:
ShellExecute ("C:\\VWorks Workspace\\VWorks\\Hit Picking\\EV2_hit_pick.xlsx")
ShellExecute("C:\\Windows\\Notepad.exe","MyFile.txt",true,5)
Note: ShellExecute() can only launch apps and documents that exist in the regular Windows file system. To launch something stored in Shared Services storage (OLSS), you first call DownloadFromStorage() and supply a directory where you want to execute it from, then call ShellExecute() (or run()) on the downloaded file.
UploadToStorage()
Uploads a record of interest (.roiZip), which is exempt from record states, to Shared Services (OLSS) storage.
Writes a JavaScript error message to the log if the upload fails.
Parameters:
1 Text string. Windows file path to the file to be uploaded.
2 Text string. The Shared Services path of the file name to be uploaded, where the file path
• May or may not begin with "[olssvr]:".
• Must be relative to the Shared Services root directory for the software edition:
"[olssvr]:VWorks Projects/VWorks/"
An extra / or \ at the beginning of the path, or after [olssvr]:, is ignored.
Note: This parameter is different from DownloadFromStorage(), where the second parameter is a destination directory. In UploadToStorage(), the second parameter is the destination path with file name. This allows UploadToStorage() to save the file to a different file name than the one it is being copied from.
3 Text string. The audit trail comment (reason for the change) for the created record of interest.
4 Boolean true/false:
– True. The software “overwrites” a file with the same file name if it already exists. The overwritten file is assigned a new version and is retained in OLSS storage along with the newly uploaded file.
– False. If a file with the same file name already exists, the software will reject the upload.
Note: Parameter 3 may be blank for VWorks Standard edition.
Examples:
UploadToStorage("C:\\VWorks Workspace\\Myfiles\\MyBarcodes.csv","[olssvr]:VWorks Projects/VWorks/Workstation/Barcodes/MyBarcodes.csv","my audit comment",false)
UploadToStorage("C:\\VWorks Workspace\\Myfiles\\MyBarcodes.csv","[olssvr]:VWorks Projects/VWorks/Workstation/Barcodes/MyBarcodes.csv","",true)
Related information
 
For information about...
See...
Using JavaScript in the VWorks software
Using JavaScript
VWorks-defined plate objects, properties, and methods
plate object
VWorks-defined task objects, properties, and methods
task object
Using JavaScript utilities
Using JavaScript utilities
JavaScript task
JavaScript
Startup and cleanup protocols
Setting up Startup and Cleanup Protocol processes
Using script variables directly in task parameters
Using simple variables
How to specify the JavaScript context for a protocol
Setting protocol options
JavaScript context and form design
Understanding JavaScript context in form design