Class Reference
IRIS for UNIX 2024.1.2
InterSystems: The power behind what matters   
Documentation  Search
  [USER] >  [Ens] >  [Config] >  [Item]
Private  Storage   

persistent class Ens.Config.Item extends %Persistent, %XML.Adaptor

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
2 17 25 2 1


Summary

Properties
AlertGroups Category ClassName Comment
CommentOrClassname DisableErrorTraps Enabled Foreground
InactivityTimeout LogTraceEvents ModifiedSettings Name
PoolSize Production Schedule Settings
VirtualSettings

Methods
%%CLASSNAMELogicalToStorage %%CLASSNAMEStorageToLogical %AddToSaveSet %AddToSyncSet
%BMEBuilt %BuildIndicesAsync %BuildIndicesAsyncResponse %CheckConstraints
%CheckConstraintsForExtent %ClassIsLatestVersion %ClassName %ComposeOid
%ConstructClone %Delete %DeleteExtent %DeleteId
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Exists
%ExistsId %Extends %GUID %GUIDSet
%GetLock %GetParameter %GetSwizzleObject %Id
%InsertBatch %IsA %IsModified %IsNull
%KillExtent %KillExtentData %LoadFromMemory %LockExtent
%LockId %New %NormalizeObject %ObjectIsNull
%ObjectModified %Oid %OnBeforeAddToSync %OnDeleteFinally
%OnDetermineClass %OnOpenFinally %OnSaveFinally %Open
%OpenId %OriginalNamespace %PackageName %PhysicalAddress
%PurgeIndices %Reload %RemoveFromSaveSet %ResolveConcurrencyConflict
%RollBack %Save %SaveDirect %SaveIndices
%SerializeObject %SetModified %SortBegin %SortEnd
%SyncObjectIn %SyncTransport %UnlockExtent %UnlockId
%ValidateIndices %ValidateObject %ValidateTable AdapterClassName
AlertGroupsBuildValueArray BusinessType CheckForIllegalCharacters Checksum
CommentOrClassnameGet ComputeAlertGroups FindSettingByName GetBusinessType
GetModifiedSetting GetSetting GetStaticSettings InactivityTimeoutGet
InactivityTimeoutSet PopulateModifiedSettings PopulateVirtualSettings QueueName
UpdateSettings XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType


Parameters

• parameter DOMAIN = "Ensemble";
• parameter XMLIGNORENULL = 1;
XMLIGNORENULL allows the programmer to override the default XML handling of empty strings for properties of type %String. By default (XMLIGNORENULL = 0), empty strings in the XML input are stored as $c(0) and $c(0) is written to XML as an empty tag. A missing tag in the XML input is always stored as "" and "" is always output to XML as no tag.

If XMLIGNORENULL is set = 1, then both missing tags in the XML and empty strings are input as "", and both "" and $c(0) are output as empty tags (i.e. <tag></tag>).

If XMLIGNORENULL is set = "inputonly", then both missing tags in the XML and empty strings are input as "". Output of "" and $c(0) are for XMLIGNORENULL = 0: $c(0) is output as an empty tag (i.e. <tag></tag>) and "" is output as no tag.

If XMLIGNORENULL = "runtime" (runtime is not case sensitive), then the behavior of XMLIGNORENULL is determined by the format parameter of XMLExport, XMLImport and %XML.Reader.OpenFile. The default behavior for XMLIGNORENULL="runtime is the same as XMLIGNORENULL=0. Adding "ignorenull" to the format argument changes the behavior to that of XMLIGNORENULL=1. "ignorenull" shoud be separated by a comma from literal/encoded part of the format. Example values for format are "", ",ignorenull", "literal,ignorenull" and "encoded,ignorenull". Note that "inputonly" is equivalent to using ,ignorenull for XMLExport and not for %XML.Reader.


Properties

• property AlertGroups as %String(MAXLEN=2500,XMLPROJECTION="NONE");
A computed property to reflect the values specified in the AlertGroups setting in Settings. The primary purpose of this property is to allow us to build the AlertGroup index on all the individual group values in the string. The actual breaking down of this value is performed in AlertGroupBuildValueArray().
• property Category as %String(MAXLEN=2500,XMLPROJECTION="ATTRIBUTE");
Optional list of categories this item belongs to, comma-separated. This is only used for display purposes and does not affect the behavior of this item.
• property ClassName as %String(MAXLEN=128,XMLPROJECTION="ATTRIBUTE") [ Required ];
Class name of this config item.
• property Comment as %String(MAXLEN=2000,XMLPROJECTION="ATTRIBUTE");
Optional comment text for this component.
• property CommentOrClassname as %String(XMLPROJECTION="NONE") [ Calculated,Transient,ReadOnly ];
Calculated comment-or-classname property.
• property DisableErrorTraps as %Boolean(XMLPROJECTION="ATTRIBUTE");
Deprecated - Always 0 : Whether to disable error traps for the job or not.
• property Enabled as %Boolean(XMLPROJECTION="ATTRIBUTE") [ InitialExpression = 1 ];
Whether this config item is enabled or not.
This value can be overridden using System Default Settings.
Overriding by a matching System Default Setting will occur even if this value is defined in the production definition.
• property Foreground as %Boolean(XMLPROJECTION="ATTRIBUTE") [ InitialExpression = 0 ];
Whether to run the job of this config item in the foreground or background.
• property InactivityTimeout as %Numeric(MINVAL=0,XMLIO="IN",XMLPROJECTION="ATTRIBUTE") [ Calculated,Transient ];
This property is now a shadow of a Host Config Setting of the same name.
• property LogTraceEvents as %Boolean(XMLPROJECTION="ATTRIBUTE") [ InitialExpression = 0 ];
Whether to log trace events for this item.
• property ModifiedSettings as list of Ens.Config.Setting(XMLPROJECTION="NONE") [ Transient ];
Same format as Settings. You must call PopulateModifiedSettings() to populate this collection. The collection contains the list of settings that are either defined in the production, or have default setting overrides.
• property Name as %String(MAXLEN=128,XMLPROJECTION="ATTRIBUTE") [ Required ];
The name of this config item. Default is the class name.
• property PoolSize as %Integer(MINVAL=0,XMLPROJECTION="ATTRIBUTE");
Number of jobs to start for this config item.
This value can be overridden with a non zero value using System Default Settings.
Overriding by a matching System Default Setting will occur even if this value is defined in the production definition.
Default value:
0 for Business Processes (i.e. use shared Actor Pool)
1 for FIFO message router Business Processes (i.e. use a dedicated job)
1 for Business Operations
0 for adapterless Business Services
1 for others
For TCP based Services with JobPerConnection=1, this value is used to limit the number of connection jobs if its value is greater than 1. A value of 0 or 1 places no limit on the number of connection jobs.
• property Production as Ens.Config.Production(XMLPROJECTION="NONE");
Reference to the Production object.
• property Schedule as %String(MAXLEN="",XMLPROJECTION="ATTRIBUTE");
Specifies times when this item should be stopped and restarted. You may enter a string formatted as a comma-separated list of event specifications, or you may enter the name of a schedule specification preceded by the @ symbol. To create a named schedule specification, use the Interoperability > Configure > Schedule Specs page.

If you wish to simply enter an event specification string in this field, it must use the following format:

action:YYYY-MM-DDThh:mm:ss[,action:YYYY-MM-DDThh:mm:ss]

Where each item in the event specification, from left to right, has the values described below:

  • action - must be either START or STOP
  • : - Required separator
  • YYYY-MM-DD - This part of the string must have one of the following two syntaxes:
    • YYYY is the year as 4 numerals, MM is the month as 2 numerals and DD is the day of the month as 2 numerals.
      Any of these fields may be the single character * (asterisk) indicating all years, all months, or all days.
    • YYYY is the string WEEK, MM is the specific occurrence of the day of the week (indicated by DD) in the month (01 = first occurrence of the specific day of the week in the month, 02 = second occurrence in the month, etc.), and DD is a specific day of the week (00 = Sunday, 01 = Monday, etc.).
      MM may be * for all occurrences and DD may be * for all days.
    Note that once a field is specified as *, all fields to the left of it are also assumed to be *. Thus, if the DD value is *, the MM value is treated as * even if it has a specific numeric value. Similarly, if MM is *, YYYY is treated as *.
  • T - Required separator
  • hh:mm:ss - Hour, minute, and second
  • , - Use the comma separator only if there is another event specification after the current one. Do not use it at the end of the Schedule string.

For example, to start the configuration item every day at 8 a.m. and stop it every day at 5 p.m. you could use the following schedule string:

START:*-*-*T08:00:00,STOP:*-*-*T17:00:00

As described at the beginning of this topic, you can also create a named schedule string. Assuming you named your schedule 'Daytime', you could then refer to your named schedule as follows:

@Daytime
• property Settings as list of Ens.Config.Setting(XMLNAME="Setting",XMLPROJECTION="ELEMENT");
Adapter and host settings specified for the adapter object and the host object.
• property VirtualSettings as list of %String(XMLPROJECTION="NONE") [ Transient ];
Contains the list of settings, value, value_type, default, default_type and other meta information. Must call PopulateVirtualSettings() to populate this collection. The format of value of each element is the following:
$LB(Target, Name, Value, ValueType, Default, DefaultType, Description, Type, MAXLEN, MINVAL, MAXVAL, VALUELIST, DISPLAYLIST, IsRequired)

Methods

• method AdapterClassName() as %String
Name of the Adapter class used by this config item.
• classmethod AlertGroupsBuildValueArray(pAlertGroups As %String = "", Output pValueArray As %String) as %Status
Helper method to allow the individual values in AlertGroups to be indexed.
• method BusinessType() as %String
The Business type of this config item.
• method CheckForIllegalCharacters(pName As %String) as %Status
Check for characters that are illegal in configuration item names. Characters | ; , : [ are not allowed at all, characters ! - $ are not allowed as first or last character, character _ is not allowed as first character as this indicates an internal private queue, and character * is not allowed as the whole config name.
• method Checksum() as %Integer
Checksum used in updating production.
• method CommentOrClassnameGet() as %String
This is a Get accessor method for the CommentOrClassname property.
• classmethod ComputeAlertGroups(pSettings) as %String
Method to compute the value of AlertGroups based on the value of the AlertGroups setting in the serialized Settings list passed in as pSettings.
• method FindSettingByName(pSettingName As %String, pTarget As %String = "") as Setting
Locate the first setting with a given name.
• classmethod GetBusinessType(pClassname As %String, pThisObject As Ens.Config.Item) as %String
Get the business type of the config item. The return value macros are defined in EnsConstants.inc.
• method GetModifiedSetting(pSettingName As %String, ByRef pValue As %String) as %Boolean
Get the config value of the named setting including resolution of system default settings, return 0 if not defined, 1 if defined.
• method GetSetting(pSettingName As %String, ByRef pValue As %String) as %Boolean
Get the config value of the named setting, return 0 if not defined, 1 if defined.
• method GetStaticSettings(ByRef pList, pDoNotRestrictToOverridable As %Boolean = 1) as %Status
Return a list of all the common static settings properties for the current config item. Or limit to just the static settings that can be overridden by System Default Settings.
• method InactivityTimeoutGet() as %Numeric
Retrieve the value of InactivityTimeout from the InactivityTimeout setting in Settings.
• method InactivityTimeoutSet(%newval) as %Status
Ensure that changes to InactivityTimeout are pushed into the InactivityTimeout setting in Settings.
• method PopulateModifiedSettings() as %Status
Call this method to initialize the ModifiedSettings collection. The collection includes settings defined in the Production as well as those ones with default setting overrides.
• method PopulateVirtualSettings() as %Status
Populate the VirtualSettings collection.
• method QueueName() as %String
Queue name used by this config item.
• method UpdateSettings(pArray) as %Status
This method updates the settings collection with the data from pArray. The settings collection is cleared first, then the entries in pArray are used to update it. The format of pArray is the following:
pArray = total number of entries
pArray(i) = $LB(Target, Name, Value)

Indices

•index (AlertGroup on Production:Exact,AlertGroups(ELEMENTS):Exact);
Index on all the group names defined in AlertGroups. The production is included in the index to ensure that the available values are correct for each production.
•index (Name on Production:Exact,Name:Exact);
Index on the name of the config item as well as which production it is associated with.

Triggers

•trigger OnChange (AFTER event INSERT/UPDATE/DELETE)
Ensure we update the modified flag after SQL changes.


Copyright (c) 2025 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.