VWorks Software User Guide : Creating a protocol: advanced topics : plateDB object
plateDB object
The VWorks JavaScript interpreter provides a plateDB object that can be accessed by a script. plateDB enables control of the inventory database through JavaScript. You can use the plateDB object to create plate groups, add plates to existing plate groups (if they exist in a location group), remove plates from plate groups, and delete plate groups.
Properties
The plateDB object has no properties.
Methods
Methods are JavaScript functions invoked through an object. The plateDB object has the following methods, which are available on systems with the inventory database option.
Syntax:
plateDB.method( )
Note: A common set of return codes are used in the applicable methods. However, based on relevance, an applicable method might use only a subset of the return codes.
 
Method
Description
createPlateGroup(string plateGroup)
Creates a new plate group.
Returns true on success, or returns false on failure. The method also prints to the log the reason for failure.
Example: plateDB.createPlateGroup("myplategroup")
deletePlateGroup(string plateGroup)
Deletes a plate group.
Returns true on success, or returns false on failure. The method also prints to the log the reason for failure.
Example: plateDB.deletePlateGroup("myplategroup")
addPlateToGroup(int side, string barcode, string locationGroup, string plateGroup)
Adds a labware that exists in a location group to a plate group.
Returns true if successful, or returns false upon failure. The method also prints the reason for failure to the log.
Note: The plate must exist in a locationGroup, and the given barcode must be on the specified side of the plate.
Example:
plateDB.addPlateToGroup(WEST,"BC01","locationGroup","plateGroup")
deleteAllPlatesFromGroup(string plateGroup)
Deletes all labware from a specified plate group.
Returns false upon failure, and prints the reason for failure to the log.
Note: The plate group must exist.
Example:
plateDB.deleteAllPlatesFromGroup("plateGroupName")
importCsvToInventory(string CSVFilepath, bool OverwriteInventory)
Imports the contents of the specified CSV file into the inventory database.
You have the option of overwriting the existing data in the database during the import process:
true—Overwrite the existing data.
false—Skip the current labware.
The method returns the following:
–1—Unknown error.
0—Method is successful.
1—Location is occupied by another labware.
2—Location is empty.
3—Device does not exist.
4—Cassette does not exist.
5—Slot does not exist.
6—CSV file does not exist in the specified directory.
Example (local file system):
plateDB.importCsvToInventory(“C:\\VWorks Workspace\\labware.csv”, true)
Example (Shared Services storage):
plateDB.importCsvToInventory("[olssvr]:VWorks Projects/VWorks/Miscellaneous/labware.csv”, true)
importLabwareToInventory(array Labware, bool OverwriteInventory)
Imports the array of labware data into the inventory database. The InventoryLabware object is passed to this method and is an element in the array.
Each array element (labware) must have the following information:
• Device
• Cassette number
• Slot number
• Labware type
You have the option of overwriting the existing data in the database during the import process:
true—Overwrite the existing data.
false—Skip the current labware.
The method returns the following:
1—Error. For errors in importing the labware, the error description is printed to main log.
0—Method is successful.
Example:
var LabwareArray = new Array();
var Labwareone = new InventoryLabware();
Labwareone.device = "Agilent Labware MiniHubl";
Labwareone.cassette = "1";
Labwareone.slot = "1";
Labwareone.type = "384 Greiner ";
Labwareone.westbc = "west";
LabwareArray[0] = Labwareone;
plateDB.importLabwareToInventory(LabwareArray,true);
clearInventory()
Deletes all labware data in the inventory database.
The method returns the following:
1—Error. The error description is printed to the main log.
0—Method is successful.
Example:
plateDB.clearInventory();
clearStorageLocation(string GroupName)
Deletes labware in the specified location group or plate group.
The method returns the following:
1—Error. The error description is printed to the main log.
0—Method is successful.
Example:
plateDB.clearStorageLocation("MyPlateGroup");
plateDB.clearStorageLocation("MyLocationGroup");
clearAbandonedLabware( )
Deletes labware that has become abandoned. Labware becomes abandoned when it moves out of storage and is somewhere in the system when a deadlock occurs or when a run is aborted.
The method returns the following:
1—Error. The error description is printed to the main log.
0—Method is successful.
Example:
plateDB.clearAbandonedLabware();
clearAllLabwareBarcodes( )
Deletes all labware barcodes in the inventory database. Other labware information is retained.
The method returns the following:
1—Error. The error description is printed to the main log.
0—Method is successful.
Example:
plateDB.clearAllLabwareBarcodes();
addLabwareToLocation(string DeviceName, string CassetteNumber, string SlotNumber, string Type, bool Overwrite)
Adds a labware to the specified storage location in the inventory database.
The method returns the following:
0—Method is successful.
3—Cassette or slot is set to ‘all’ and the device does not exist or is disabled.
4—Cassette out of range.
5—Slot out of range.
1—Other error.
The error description is printed to the main log.
Example:
plateDB.addLabwareToLocation("Agilent Labware MiniHub","1","1","384 Greiner",true);
plateDB.addLabwareToLocation("Agilent Labware MiniHub","all","1","384 Greiner",true);
plateDB.addLabwareToLocation("Agilent Labware MiniHub","1","all","384 Greiner",true);
plateDB.addLabwareToLocation("Agilent Labware MiniHub","all","all","384 Greiner",true);
deleteLabwareAtLocation(string DeviceName, string CassetteNumber, string SlotNumber)
Deletes a labware from the specified storage location.
The method returns the following:
0—Method is successful.
2—Location is empty.
3—Cassette or slot is set to ‘all’ and the device does not exist or is disabled.
4—Cassette out of range.
5—Slot out of range.
1—Other error.
The error description is printed to the main log.
Example:
plateDB.deleteLabwareAtLocation("Agilent Labware MiniHub","1","1");
plateDB.deleteLabwareAtLocation("Agilent Labware MiniHub","all","1");
plateDB.deleteLabwareAtLocation("Agilent Labware MiniHub","1","all");
plateDB.deleteLabwareAtLocation("Agilent Labware MiniHub","all","all");
getLocationByBarcode(string Barcode)
Obtains the location of a labware using the supplied barcode.
Returns an array of labware (InventoryLabware objects) if the method is successful. Otherwise, the method returns a null array.
Example:
var LabwareArray = new Array();
LabwareArray = plateDB.getLocationByBarcode("barcode");
exportDatabase(string FileName)
Exports the data in the inventory database to an SQL file.
The method returns the following:
0—Method is successful.
6—File path is invalid.
1—Other error.
Example (local file system):
plateDB.exportDatabase("C:/VWorks Workspace/exportedfile.sql")
Example (Shared Services storage):
plateDB.exportDatabase("[olssvr]:VWorks Projects/VWorks/Miscellaneous/SQL Files/exportedfile.sql")
Note: The "[olssvr]:" prefix to the file path specifies the exported file as a record of Interest and opens the Audit Comment dialog box.
importDatabase(string FileName)
Imports the data from the specified SQL file into the inventory database.
The method returns the following:
0—Method is successful.
6—File path is invalid.
1—Other error.
Example (local file system):
plateDB.importDatabase("C:/VWorks Workspace/importedfile.sql")
Example (Shared Services storage):
plateDB.importDatabase("[olssvr]:VWorks Projects/VWorks/Miscellaneous/SQL Files/importedfile.sql")
enumeratePlateGroup(string plateGroup)
Returns an array of strings corresponding to the IDs of all plates in the specified plate group.
If the method fails, the reason for failure prints to the log.
Note: The plate group must exist.
Example:
plateDB.enumeratePlateGroup("plateGroupName")
See additional example in getPlateBarcode method, below.
getPlateBarcode(int side, array plateID)
Returns the plate barcode (string) on the specified side of the specified plate.
If the method fails, the reason for failure prints to the log.
Example:
var plateIDs = plateDB.enumeratePlateGroup("plateGroupName")
for(var plateID in plateIDs){
print(plateDB.getPlateBarcode
(WEST, plateIDs[plateID]))
}
enumerateListOfGroups(int groupType)
Returns an array of strings consisting of all group names in the Inventory database. groupType specifies which kind(s) of groups, where
0 = both types (plate groups and location groups)
1 = plate groups only
2 = location groups only
If the method fails, the reason for failure prints to the log.
Example:
var group_array = plateDB.enumerateListOfGroups(0)
getLabwareInfo(string labwareName)
Returns a string containing well information about the given labware entry in the following format:
"NumberOfWells=<number>"
If the labware database does not contain a labware entry with the given name, the method returns an empty string.
Example:
plateDB.getLabwareInfo("96 Greiner Polystyrene Clear Round Well, Flat Bottom")
Related information
 
For information about...
See...
Using JavaScript in the VWorks software
Using JavaScript
VWorks-defined functions
VWorks-defined functions
Other VWorks-defined objects
Using JavaScript utilities
Using JavaScript utilities
JavaScript task
JavaScript
Startup and cleanup protocols
Setting up Startup and Cleanup Protocol processes