Share

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

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

Was this information helpful?