WSDatabase
A database, including cloud databases and transportable databases.
The majority of these methods are only available in Exchange, there is only limited functionality in the UI. A database can be accessed from WSApplication.open
(with Exchange) or WSApplication.current_database
(with UI).
Methods:
- copy_into_root
- file_root
- find_root_model_object
- guid
- list_read_write_run_fields
- model_object
- model_object_collection
- model_object_from_type_and_guid
- model_object_from_type_and_id
- new_model_object
- new_network_name
- path
- result_root
- root_model_objects
copy_into_root
#copy_into_root(object, copy_results, copy_ground_models) ⇒ WSModelObject
EXCHANGE
Copies a WSModelObject and any children into the database root, returning the new model object. The model object being copied could be from the same database, or another database such as a transportable database.
Parameters
Name | Type(s) | Description |
---|---|---|
object | WSModelObject | The model object to copy. |
copy_results | Boolean | Whether to copy simulation results, if the model object (or it's children) have simulations with results. |
copy_ground_models | Boolean | Whether to copy ground models. |
Return | WSModelObject | The newly copied object in this database. |
file_root
#file_root ⇒ String
EXCHANGE
, UI
Returns the path used by this database for files such as GIS layers, also known as the Remote Files Root.
This is the path shown in the UI under File > Database Settings > Set Remote Roots > Remote Files Root.
If this is a standalone database, and "force all remote roots to be below the database" is enabled, then the path will be the folder containing the database.
find_root_model_object
#find_root_model_object(type, name) ⇒ WSModelObject?
EXCHANGE
, UI
Returns the WSModelObject at the root (top level) of the database. Model objects at this level will have unique names.
The valid types at this level are Asset Group
, Model Group
, and Master Group
.
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object. |
name | String | The name of the object (case sensitive). |
Return | WSModelObject, nil | The object if found, nil otherwise. |
guid
#guid ⇒ String
EXCHANGE
, UI
Returns the GUID for the database, which is also called the database identifier in the user interface.
puts database.guid
=> 'CEB7E8B9-D383-485C-B085-19F6E3E3C8CD'
Parameters
Name | Type(s) | Description |
---|---|---|
Return | String |
list_read_write_run_fields
#list_read_write_run_fields ⇒ Array<String>
EXCHANGE
, UI
Returns the field names in run objects that are read-write i.e. fields that can be set from Exchange scripts.
database.list_read_write_run_fields.each { |field| puts field }
Parameters
Name | Type(s) | Description |
---|---|---|
Return | Array<String> |
model_object
#model_object(path) ⇒ WSModelObject?
EXCHANGE
, UI
Finds a WSModelObject in the database using its scripting path.
network = database.model_object('>MODG~My Root Model Group')
raise "Could not find network" if network.nil?
Parameters
Name | Type(s) | Description |
---|---|---|
path | String | The scripting path to the object. |
model_object_collection
#model_object_collection(type) ⇒ WSModelObjectCollection
EXCHANGE
, UI
Finds all WSModelObjects in the database of a given type.
database.model_object_collection('Rainfall Event').each do |model_object|
puts model_object.name
end
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object. |
Return | WSModelObjectCollection | The object(s) found, will be an empty collection if there are no objects of this type. |
model_object_from_type_and_guid
#model_object_from_type_and_guid(type, guid) ⇒ WSModelObject?
EXCHANGE
, UI
Finds a WSModelObject in the database using its scripting type and GUID. The GUID can be found in the user interface via the properties dialog.
rainfall = database.model_object_from_type_and_guid('Rainfall Event', '{CEB7E8B9-D383-485C-B085-19F6E3E3C8CD}')
raise "Could not find rainfall" if rainfall.nil?
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object. |
guid | String | The creation guid. |
Return | WSModelObject, nil | The object if found, nil otherwise. |
model_object_from_type_and_id
#model_object_from_type_and_id(type, id) ⇒ WSModelObject?
EXCHANGE
, UI
Finds a WSModelObject in the database using its scripting type and ID. The ID can be found in the user interface via the properties dialog.
rainfall = database.model_object_from_type_and_id('Rainfall Event', 1)
raise "Could not find rainfall" if rainfall.nil?
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object. |
id | Integer | The model id. |
Return | WSModelObject, nil | The object if found, nil otherwise. |
new_model_object
#new_model_object(type, name) ⇒ WSModelObject
EXCHANGE
Creates a WSModelObject in the root of the database.
The valid object types at this level are Asset Group
, Model Group
, or Master Group
.
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object - must be a valid type for this level of the database. |
name | String | The name of the new object, must be unique. |
Exceptions
- unrecognised type - if the object type is not valid
- invalid object type for the root of a database - if the object type is valid, but not allowed for this level of the database (see method description)
- an object of this type and name already exists in root of database - object names must be unique
- licence and/or permissions do not permit creation of a child of this type in the root of the database - if the object cannot be created in the root of the database for licence and/or permission reasons (not applicable to some products / licenses)
- unable to create object - if the creation fails for some other reason
new_network_name
#new_network_name(type, name, branch, add) ⇒ String
EXCHANGE
, UI
Generates a new network (model object) name. This is intended to be used with an existing model object's name to generate a unique variant for a new network model object.
new_name = database.new_network_name('Model Network', 'Badger', false, false)
⇒ Badger#1
Parameters
Name | Type(s) | Description |
---|---|---|
type | String | The scripting type of the object. |
name | String | The base name. |
branch | Boolean | If true, the number increment will be an underscore e.g. mynetwork_1 . if false, it will be a hash symbol e.g. mynetwork#1 . |
add | Boolean | If true, #1 or _1 will always be appended to the name, instead of incrementing the number. |
Return | String | The new name. |
path
#path ⇒ String
EXCHANGE
, UI
Returns the path of the database.
This is the same path that would be used by WSApplication.open, for example:
- Transportable database: 'C:/Badger/MyDatabase.icmt'
- Standalone database: 'C:/Badger/MyDatabase.icmm'
- Workgroup database: 'localhost:40000/Badger/MyDatabase'
Parameters
Name | Type(s) | Description |
---|---|---|
Return | String |
result_root
#result_root ⇒ String
EXCHANGE
Returns the path used by this database for results files when results are stored 'on server', also known as the Remote Results Root.
This is the path shown in the UI under File > Database Settings > Set Remote Roots > Remote Results Root.
If this is a standalone database, and "force all remote roots to be below the database" is enabled, then the path will be the folder containing the database.
root_model_objects
#root_model_objects ⇒ WSModelObjectCollection
EXCHANGE
, UI
Finds all the objects at the root (top level) of the database.