Defining a Subscription Descriptor

InfoHub implements alerts and notifications with GT.M triggers on ^InfoHubInfo nodes. With one exception, a Subscription Descriptor essentially defines a trigger. A Subscription Descriptor specifying a condition of "Noinfo" differs slightly, in that it starts a Noinfo process which periodically checks for data in ^InfoHubInfo and if it finds none, places a "key:value" pair in the alert queue and sends an INTRPT to its Subscriber process(es). The syntax of the Subscriber Descriptor is:

Subscription:{InfoDictID | InfoDictName}:[SubscriptionName]: [SubscriptionID]:{InfoDictID | InfoDictName}:{InfoDictItemID | InfoDictItemName}:Condition:[Value]:[Period]:[entryref]:[SubscriberID[,...]]:[PublisherID[,...]]

InfoDictID or InfoDictName: The first InfoDict ID or Name identifies the InfoDict holding the defined Subscription.
The first InfoDictName or InfoDictID specifies the domain which maps SubscriptionID to SubscriptionName.
SubscriptionName: The name of the Subscription.
SubscriptionID: A unique 31-bit positive integer that uniquely identifies a subscription.
The descriptor must specify one, or both, of the SubscriptionName and SubscriptionID. When the descriptor specifies both the Name and ID and there is no corresponding InfoDict entry, configuration processing implicitly creates an InfoDict entry. If the Configuration File specifies the same ID for more than one Subscription associated with a Publisher, the configuration processing produces an IHDUPSUBSCRPTN error.
If SubscriptionName is specified, the configuration gets SubscriptionID from the first specified InfoDict domain. if the specified domain has no definition for the Name, the InfoHub configuration process generates a new unique random 31-bit positive integer to use (that is, SubscriptionID is unique for each InfoHubID), and stores it in the InfoDict domain in association with the SubscriptionName.
If the configuration detects there is no Name or ID for a Subscription, it produces an IHIDORNAMEREQ error. Attempting to configure a subscription that has a corresponding InfoDictItem with no relationship to a Publisher produces an IHSUBSCRPTNNOPATH error.
The SubscriptionID can be used by the subscriber to determine the condition that caused the alert to fire. This provides context for the item reference and value contained in the alert.
InfoDictID or InfoDictName: The second InfoDict ID or Name identifies the InfoDict holding the defined InfoDictItem to "watch."
InfoDictItemName or InfoDictItemID specifies the item that the Subscription must "watch." If the configuration detects there is no valid Name or ID for an InfoDictItem, it produces an IHIDORNAMEREQ error. Attempting to use a NoInfo Subscription on a META node produces an IHMETANOINFO error. Attempting to use a Subscription on a NONE node produces an IHTNONENOSUB error.
Condition: Condition specifies a GT.M binary relational operator excluding concatenation and non-relational arithmetic operators or the (case-insensitive) text: "Noinfo" which configures detection of a period during which the specified item receives no new data. If configuration processing does not recognize a valid Condition, it produces an IHSUBCONDINV error. Pattern conditions have a patcode immediately following the pattern operator (?) in the condition field, and nothing in the value field. If configuration processing can't compile the patcode, it produces a IHSUBCONDINV error.
Value: Value specifies a GT.M literal which the Subscriber relates to the Item; it is required except for the "Noinfo" or pattern conditions; if the configuration processing detects there is no valid literal, it produces an IHSUBVALREQLIT error; if it detects a value for a "Noinfo" condition, it produces an IHNOINFONOVAL error; if it detects a value for a pattern (?) condition, it produces an IHPATNOVAL error; if the comparison is not value, it produces an IHSUBSPROB error.
Period: Period specifies a time in seconds and indicates checking over the Period for changes in the Item the value using a condition containing a "less-than" ("<") or "greater-than" (">"), effectively supporting rate checking. If the configuration detects a non-numeric rate, it produces an IHSUBINVPER error; if it detects a period with a condition that does not contain "<" or ">", it produces an IHBADCOND4PER error. Configuration processing accepts an empty period for all conditions except "Noinfo", for which configuration processing produces an IHNOINFOINVPER error for an invalid period.
Entryref: Entryref signifies a GT.M entryref specifying the action for the Subscription to take. By default, the InfoHub uses a routine called ^InfoHubNotify for Values without Periods and ^InfoHubRate(Value,Period) for Values with Periods. Any user defined entryref must be available in the $ZROUTINES of the Publisher process.
The optional SubscriberIDs are useful when there are multiple adapters with differing Subscriptions; in that case by default, a Subscription applies to all Subscribers. If configuration processing detects a SubscriberID that is not defined, it produces an IHBADSUBSCRIBER error.
The optional PublisherIDs are useful when there are multiple Publishers with differing Subscriptions; in that case by default, a Subscription applies to all Publishers. If configuration processing detects a PublisherID that is not defined, it produces an IHBADPUBLISHER error.
Note that to easily subscribe to an error from a FileLine or PipeLine process that FileLine or PipeLine process must set an appropriate node, defined in the InfoDict, which, in case of an error, those processes update uniquely. Attempting to configure an InfoHub with a Subscription that does not define a usable trigger produces an IHTRIGPROB error.

	InfoHub Internals
InfoHub implements other alerts with GT.M triggers on InfoHub nodes. A Subscription Descriptor other than "Noinfo" defines a trigger. The technique of using GT.M triggers to implement Subscriptions does not work for NoInfo Subscriptions because triggers are initiated by a database update, whereas NoInfo is initiated by the absence of an update. To manage polling impact, each NoInfo subscription is implemented with a process that executes a Hang for the Period at the end of which it might need to queue an alert and INTRPT one or more Subscribers. When the Hang expires, the process checks whether or not the information it is monitoring has changed. If it has, the process notes the time at which it changed, and schedules itself for the future with another Hang. If it has not changed, the process makes an appropriate entry in ^InfoHubInfo, issues the alert / notification, and schedules itself for the future with a Hang for the Period. Because the META type aggregation mechanism uses a trigger on a node that manages Subscriber notifications for its Subscription and suppresses storing of data at the trigger node, a NoInfo process has no means to track activity at a META node. Configuration processing stores Subscription specifications in the following nodes: InfoHubConf(InfoHubID,"Subscriptions",SubscriptionID,BeginningSequenceNumber)=a?? [EndingSequenceNumber]:a??SubscriptionInfodictID:a??ItemInfoDictID:a??InfoDictID:a??condition:a??value:a??[period]:a??[entryref]:a??[SubscriberID[,...]]:a??[PublisherID[,...]] ^InfoHubConf(InfoHubID,"NoInfo",SubscriptionID,BeginningSequenceNumber)=a??

InfoHub Internals

InfoHub implements other alerts with GT.M triggers on InfoHub nodes. A Subscription Descriptor other than "Noinfo" defines a trigger.

The technique of using GT.M triggers to implement Subscriptions does not work for NoInfo Subscriptions because triggers are initiated by a database update, whereas NoInfo is initiated by the absence of an update. To manage polling impact, each NoInfo subscription is implemented with a process that executes a Hang for the Period at the end of which it might need to queue an alert and INTRPT one or more Subscribers. When the Hang expires, the process checks whether or not the information it is monitoring has changed. If it has, the process notes the time at which it changed, and schedules itself for the future with another Hang. If it has not changed, the process makes an appropriate entry in ^InfoHubInfo, issues the alert / notification, and schedules itself for the future with a Hang for the Period. Because the META type aggregation mechanism uses a trigger on a node that manages Subscriber notifications for its Subscription and suppresses storing of data at the trigger node, a NoInfo process has no means to track activity at a META node.

Configuration processing stores Subscription specifications in the following nodes:

InfoHubConf(InfoHubID,"Subscriptions",SubscriptionID,BeginningSequenceNumber)=a?? [EndingSequenceNumber]:a??SubscriptionInfodictID:a??ItemInfoDictID:a??InfoDictID:a??condition:a??value:a??[period]:a??[entryref]:a??[SubscriberID[,...]]:a??[PublisherID[,...]]

^InfoHubConf(InfoHubID,"NoInfo",SubscriptionID,BeginningSequenceNumber)=a??

Example:

Subscription:SysSubscriptions:PatchMe:1000:UpTime:Days:<:30:::404:
Subscription:SysSubscriptions:AuthFail:2000:GenericAny:Anything:[:""""Fail"""":::503:
Subscription:SysSubscriptions:GTMError:3000:GenericAny:Anything:[:""""%GTM-E""""::::

This example configures 3 subscriptionsa??PatchMe, AuthFail, and GTMError. PatchMe is for Subscriber ID 404 and AuthFail is for Subscriber ID 503. GTMError is for all Subscribers. This example is a part of SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA	Up	A Next
A	Home	A

Defining a Subscription DescriptorChapterA 4.A Configuring an InfoHub

Defining a Subscription Descriptor

Defining a Subscription Descriptor
ChapterA 4.A Configuring an InfoHub