EquipGetProperty

This function reads a property of an equipment database record from the EQUIP.RDB database file.

This function is a blocking function. It blocks the calling Cicode task until the operation is complete.

Syntax

STRING EquipGetProperty(STRING Name, STRING Field, INT Mode, STRING Cluster)

Name:

The name of the equipment from which to get information. The name of the equipment can be prefixed by the name of the cluster that is "ClusterName.Equipment".

Field:

The field to read. The supported fields are:

Name, Alias, Cluster, Type, Location, Page, Parent, Content, Help, Comment, TagPrefix, IODevice, Hidden, Area, Custom1, Custom2, Custom3, Custom4, Custom5, Custom6, Custom7, Custom8, Defstate, Scheduled, SchedID, DevSched, Param.

• Name — The name of the equipment (254 characters).

• Alias — The display name. A name used to identify the equipment at runtime. (254 characters).

• Cluster — The cluster to which the equipment belongs (16 characters).

• Type — The associated equipment type (254 characters).

• Location — Equipment-specific field that describes its location (254 characters).

• Page — The name of the page that hosts the piece of equipment (254 characters).

• Parent — The name of the parent equipment derived from the equipment name (maximum 254 characters).

• Content — Workspace content associated with equipment instance.

• Help — Help context (254 characters).

• Comment — User comment (254 characters).

• TagPrefix — A prefix applied to any tags generated for the equipment instance (79 characters).

• IODevice — The name of I/O device that communicates with the equipment (254 characters).

• Hidden — Indicates if the equipment is hidden at runtime (returns 0 or 1).

• Area — Area number (integer) (16 characters). If an area is not specified, zero (0) will be returned.

• Custom1..8 — User definable fields (254 characters each).

• Defstate — The default state.

• Scheduled — Specifies if the equipment participates in a schedule (returns 0 or 1).

• SchedID — The ID of the required schedule on the BACnet device (16 characters).

• DevSched — Specifies if the required schedule is retrieved from the BACnet device (returns 0 or 1).

• Param — Custom parameters. This field will be empty if the project has been migrated to use the Configuration Parameters database.

Runtime fields:

• MODE — the current mode of the equipment. 0 = automatic; 1= manual inherited; 2= manual.

• DRMODE — the current DR mode level for the equipment. The value will be a positive integer to represent the current DR level or zero if inactive.

• STATE — the current state of the equipment. Although you can only set the state for equipment in Override mode, it is still possible to get the state for equipment in normal and inherited override mode.

Mode:

0 Block — values are retrieved from the report server, the value will also be stored in local memory cache.

1 Cache — values are first retrieved from local memory cache, if the property is missing from the memory cache, a request will be sent to the report server and the result will then be cached. If the property is missing from the memory cache, an empty string will be returned.

2 Local — values are retrieved from the local RDB. Error 348 (Property does not exist) will be returned if the property requested is not available. Requesting runtime fields will also return this error.

3 CacheThenLocal — values are first retrieved from local memory cache, if the property is missing from the memory cache, a request will be sent to the report server and the result will then be cached. If the property is missing from the memory cache, the local RDB will be accessed to retrieve the property value.

Cluster

The name of the cluster (optional for a single cluster system).

Note: Mode 1 and 3 will access the report server at least once, which means there will be a one-off performance penalty on the report server. To make sure the equipment property values are the latest, the cached values will be refreshed from the report server when necessary. For non-runtime properties, refresh only occurs when report server is reloaded or recovers from network disruption. For runtime properties, the cached value will be periodically refreshed based on value of the INI parameter [Client]EquipCacheTimeout. Mode 2 will be the fastest, but cannot guarantee equipment will be up-to-date (see Client Side Online Changes). Mode 0 will be the slowest as each request is sent across the wire and the function will block until the report server responds.

Return Value

The value of the specified field as a string. An empty string may or may not be an indication that an error has been detected. The last error should be checked in this instance to determine if an error has actually occurred.

Related Functions

EquipBrowseClose, EquipBrowseFirst, EquipBrowseGetField, EquipBrowseNext, EquipBrowseNumRecords, EquipBrowseOpen, EquipBrowsePrev, EquipCheckUpdate, EquipSetProperty

See Also

Equipment Database Functions