Defining a User Record

Comment Lines start with a '!' character

Each record in the user record definition file is defined using the following syntax:

RECORD 
NAME 			[<language-id>] <short_record-name>
LONG_NAME 		"<long_record_name>"
DESC 			[<language-id>] "<record-description>"
REFERENCES		<parent-record-long-name>
SYMBOLIC_SERVER #MSGRT
ID_LENGTH 		<length>
OPTIONS 		<options>

Example:

RECORD
NAME ENG 		ALLFIELD
LONG_NAME 		"SampleREcordWithAllFields"
DESC ENG 		"Test record with all field types"
SYMBOLIC_SERVER #MSGRT
ID_LENGTH 		10
OPTIONS 		NAMED

Syntax Elements

RECORD

It defines the beginning of a new record definition.

NAME [<language-id>]

This is the record 'short' name which all record definitions must have. The 'short' name is not particularly visible, but it is used internally and must be defined. The <language-id> function is not currently implemented so this value can be omitted.

The 'short' record name:

  • Can contain a maximum of 8 characters,

  • Can include alphanumeric and underscore (“_”) characters but not hyphens (“-“),

  • Must begin with an alphabetic character (non-numeric).

  • Must be unique across all record definitions. However, the 'short' and 'long' names for the same record definition may be identical.

  • Are case insensitive, e.g. LinNum and LINNUM are the same field.

A record 'short' name must not be changed after the record has been in use. It is a unique identifier used in Database Collections and may be used elsewhere for similar purposes. Changing the name may create version incompatibilities or prevent access to data.

LONG_NAME

The LONG_NAME allows for a longer, more descriptive name for the record to be added. This name is the one commonly seen in the Windows Client when selecting records in the configuration of Displays, Thresholds, etc. 'Long' record names may be quite lengthy, but for practical purposes (fitting in dialogs etc), they are best kept to under 32 characters.

The 'long' record name:

  • Must be contained within quotes,
  • Can include alphanumeric and underscore (“_”) characters but not hyphens (“-“),

  • Must begin with an alphabetic character (non-numeric),

  • Must be unique across all record definitions. However, the 'short' and 'long' names for the same record definition may be identical,

  • Are case insensitive, e.g. "LineNumber" and "LINENUMBER" are the same field.

A record 'long' record name can be changed if required, the only limitation being the potential confusion caused to existing users who may be familiar with the previous name.

DESC [<language-id>]

This is the record description, which is displayed in the tooltips when selecting records and fields or when hovering over tabular display headings in the user interface. The <language-id> function is not currently implemented and can be omitted.

The description is enclosed in quotations and can be up to 32,767 characters long. However, in practice, more than 20 or so lines will be of limited value in the user interface. In the tooltips, if the lines of the record description plus the lines of field description exceed the screen size, then they will be truncated and there is no way to scroll tooltips.

The parser ignores leading spaces on secondary lines so that they can be lined up without affecting the resulting actual alignment.

REFERENCES

Defines this record as extension to <parent-record-long-name>. This element only has meaning when OPTIONS COMPONENT is also specified.
The rows in this record will be referencing the rows in the parent record through the fields having OPTION DEVICE in both records, or if omitted, the meta field NODE will be used instead.
For one-to-many relationship, the field having OPTION COMPONENT in this record will be used to identify the row within the group of rows in this record that references the same row in the parent record.

This relationship definition is used to identify alerts raised for components within monitored devices and is part of the Alert Suppression feature in Managing nodes.

SYMBOLIC_SERVER

This is a mandatory parameter that should be completed with the default setting of #MSGRT.

ID_LENGTH

This represents the size in bytes of the collective set of fields that uniquely identify each record instance, that is, the 'Key' fields.

Key fields start from the field containing the START_ARRAY token and include each following field until their accumulated length matches the ID_LENGTH value. For example, a record with an ID_LENGTH of 4 has two Key fields, each one with a TYPE value of BINARY_16 (i.e. 2 bytes each).

The maximum ID_LENGTH value is 640 bytes. An ID_LENGTH of 0 is valid as this means that there are no key fields and therefore only a single row of data for the record will ever be delivered at a time.

ID_LENGTH must be an even number of bytes and must be the accumulated size of all Key fields (taken from the TYPE value of each field). For this reason, it is recommended to define the fields that are to form the key FIRST. If this value is not set to the exact total size of the fields that make up the key the following message will be displayed.

"Record ID length is not at boundary defsrec:<nnn>:<record_name>".

Where <nnn> is the line number of the record definition in error and <record_name> is the name of the affected record."

TIMESTAMP and RESPONSE_TIME fields are 12 bytes long, not 8 as you might guess from looking at their definition. See details in the DISPLAY_OPTION section of Defining a Field for a User Record.

In designing a unique key, it is necessary to consider that the key must continue to be unique over time. For example, at any point in time, a running process on a machine might be uniquely identified by a PID or process ID. However, over time, processes stop and start and PIDs get re-used, so a key of PID by itself is not sufficiently unique for use as the Record key. A compound key of (PID, ProcessStartTime) would be a good solution.

If the key is not unique data will be lost.

OPTIONS

There are a variety of record options that can be applied for various effects. Multiple options must be space separated.

DEVICE Defines this record as a primary record for monitored devices. See Alert Suppression for more information.
COMPONENT Defines this record as an extension record. For more details, see the REFERENCES token above and the OPTION section of Defining a Field for a User Record.

COLLATED

If a record is provided by more than one collector on a single server and each collector instance provides its own unique set of record instances, the record can usefully be defined with OPTIONS COLLATED. When a view of the record is created, the view request will be sent to all instances of collectors registered to provide the record. When the data is delivered from all of the collectors at each interval, it will be collated in the IRNETRTR process, before being forwarded to the original requesting process (Windows Client, Web Application, Database, another node, etc).

HISTORICAL

Some records are about data that is inherently historical in nature. Typically, this means some kind of event data. For example, it could be system event records or any other event log data collected.

HISTORICAL record definitions will typically have a TIMESTAMP field as one of their key fields (included by ID_LENGTH).

Collections of HISTORICAL records would usually be coded to maintain a history of recent events and be capable of delivering either its full set of cached events or just the new events that have occurred during the last sampling interval.

NAMED

'Named' or 'Associate' records have pre-selection criteria provided to the collector at collection creation time. The purpose of associates is usually to allow improved collection performance by pre-specifying the data to be gathered, rather than having the collector gather all possible data and post-filtering it.

Typically, the associate value is some kind of name or identifier of the entities to be collected (hence NAMED). However, as a more general specification, interpretation of the associate data passed to a collection is entirely at the discretion of the collector. Specification at the user interface is free format text, with the possibility of automatic token substitution.

This associate criterion is represented in a field of the resulting record data and must be delivered back in that field. There is no syntactic specification to specify which field is the associate field. There is however, a convention that must be adhered to if you want it to work. The associate field is "the first field that is not the ARRAY_OCCURS field". There is also a size limitation. Associate fields may only be up to 64 bytes in length.

SUPPRESS

Hides the record definition. The record will not be available for selection in the user interface if OPTIONS SUPPRESS is specified. Often used temporarily when new records are under construction or longer term if a record has been obsoleted and its record Id has not yet been re-used.

MERGED

This option is the same as the COLLATED option, except that it does not assume that the record instances that are delivered from each collector will be unique. This is a more expensive collation in IRNETRTR but it does remove duplicates.

The combination of HISTORICAL and NAMED Options is not allowed.
Provide feedback on this article