SENSE Architecture & Specification: Appendices

V0.13 RBLandau 19960519

Appendix A:

Error Codes

All SENSE API entry points return status codes of C data type 'int'. If the status return is non-zero, it represents an error, or at least a warning, as specified below.

Table 1: Error codes returned by API calls
SFERR_NOERROR 0No error, success, normal return, okay, cool, copascetic.
SFERR_ADDRNOTAVAIL 1Network address not available: cannot bind to address
SFERR_BADCONTEXT 2Invalid server context
SFERR_BADPARAM 3Invalid parameter
SFERR_CALLBACKSTOP 4Callback function requested stop
SFERR_COMMERROR 5Communications error
SFERR_DATATOOBIG 6Data too big: resulting message could not be transmitted
SFERR_INTERRUPTED 8Process was interrupted
SFERR_NOACCESS 9Access not allowed
SFERR_NOITERATOR 10No GetFirst operation to begin iteration
SFERR_NOMEMORY 11Memory allocation failure
SFERR_NOMOREROOM 12No more room, Namelist full: too many publications, clients, subscriptions, etc.
SFERR_NONEXT 13No next item (end of list)
SFERR_NOSERVER 14Server not responding
SFERR_SYSTEM 16System level error; on POSIX-compliant system, see errno
SFERR_VARNAMETOOBIG 18Variable name too big
SFERR_VARNOTFOUND 19Variable not found
SFERR_VARVALTOOBIG 20Variable value too big
SFERR_PROTOERROR 21Protocol error: missing mandatory property
SFERR_DUPLICATE 22Duplicate instance or operation
SFERR_NOTYETIMPLEMENTED 23Feature not yet implemented

Appendix B:

Reserved Properties

Why Do We Need Reserved Properties?

To enable vendors to build interoperable Publisher and Subscriber applications, most of the standard SENSE objects have some special properties that should be present and shall be named according to the following conventions.

Reading any of the reserved property names will always return a value and never return an error (except in the case of an access control violation). If the property has not been declared and given a value in the Server, then the Client API shall return an appropriate null value, a zero-length string.

Reserved Property Names

Some properties apply to many objects. The "Id" property group contains any property that might, arguably, apply to any SENSE object; that is, its name begins with the prefix "Id." Some properties may be specific to certain object types, and will be named appropriately.

In general, not all properties will be supplied for all objects. If a Client retrieves a property that is not defined, the result is, in general, a NULL pointer; in cases where the caller has already supplied memory for a value, the returned value is a zero-length (null-terminated or counted, depending on the interface) string.

Table 2: Names of reserved properties
Condition.CodePublication, Edition, Event, ServerintegerOne of the following, corresponding to the given named conditions.
See Appendix J for a description of condition codes.
Condition.TextPublication, Edition, Event, ServerstringTextual description of the condition. This should include human-readable, explanatory information, especially in the case of warning and attention conditions.
Condition.TimestampPublication, Edition, Event, ServerdateThe time at which the Condition last changed, or the time that the Condition was first declared. Number represented as yyyymmddHHMMSS.uuuuuu-ooo, the DMI standard date format, including microseconds and GMT offset in minutes.
Condition.Last.CodePublication, Edition, Event, ServerintegerPrevious value of Condition.Code.
Condition.Last.TextPublication, Edition, Event, ServerstringPrevious value of Condition.Text.
Condition.Last.TimestampPublication, Edition, Event, ServerdatePrevious value of Condition.Timestamp.
Edition.IdlistPublication, Serverlist of integersComma-separated list of the Id numbers of the extant Editions of a specific Publication, or of all Publications in the Server.
Id.App.NameClient, ServerstringSupporting software name.
Id.App.VersionClient, ServerstringSupporting software version.
Id.ClassClient, PublicationstringSENSE class id.
See Appendix K for list of class id values.
Id.IdAllstringClient registration id, server-assigned. (Numeric)
Id.ContactClient, PublicationstringsysContact equivalent.
Id.CreatedPublication, EditiondateTimestamp when Publication was created.
Id.DescriptionClient, PublicationstringsysDescription equivalent.
Id.Host.AddressClient, PublicationstringLocal host address.
- For IP host, IP address in (numeric) dotted octet notation.
- For IPX host, tbs.
- For AppleTalk host, tbs.
Id.Host.IdClient, PublicationstringPlatform-specific host id. On platforms supporting a unique identifier for licensing, that identifier value.
Id.Host.NameClient, ServerstringLocal host name.
- for IP host, fully-qualified internet name in dotted form.
- For IPX host, tbs.
- For AppleTalk host, tbs.
"PublicationstringThe Id.Host.Name value of the primary Publisher that registered the Publication.
Id.Host.PlatformClient, PublicationstringPlatform descriptor. [[rules tbs]]
Id.InstalledPublicationdateDate when entity was installed, from Installed item in DMI ComponentID Group.
"Server, ClientdateDate when software was installed.
Id.LocationClient, PublicationstringsysLocation (MIB-II) equivalent.
Id.ManufacturerPublicationstringVendor/creator information, from DMI ComponentID Group.
Id.ModifiedPublicationdateWhen the Publication was last modified.
Id.NamePublicationstringPublication name. This name should be a short name, a given name suitable as an icon label, for instance. Generally not a fully-qualified, formal name (which is in Id.Host.Name).
"EditionstringRegistered name of Edition, defining syntax, additional properties, event subset, periodicity, etc. See Appendix xx.
Id.ObjectIdPublicationstringsysObjectId (MIB-II) equivalent.
Id.ProductPublicationstringRelated product name.
Id.SenseVersionClientstringVersion of SENSE communication protocol being used between Client and Server.
"ServerstringHighest version of SENSE communication protocol supported by Server.
Id.SerialNumberClient, ServerstringFrom DMI ComponentID Group.
Id.SignaturePublication, ClientstringQuasi-password for privileged Publication operations, such as registering a persistent Publication or modifying Publication properties. Such security features are Server implementation-dependent.
Id.StartedPublication, ServerdateWhen the entity was most recently started (rebooted, power-cycled, etc.).
Id.URLClient, PublicationstringTop-level URL, supplied by the vendor.
Id.VersionPublicationstringVersion information, from DMI ComponentID Group.
etc. tbs

Appendix C:

Configuration Options

Where is the Publisher located?

The Publishers for an managed object in the network may be inside the object or outside it, logically or physically.

Where is the Server located?

Servers, like Publishers, can be located inside a device or external to it in the network, both logically and physically.

If a large number of devices in a network include Servers, then the large number of servers can cause management problems.

In any case, a site may wish to reduce the number of servers to simplify management, simplify configuring Subscriber Clients, and to simplify the process of discovery by Clients. Sites can tailor the number and location of Servers, and the availability of Publications and Editions, using the Replicator application, described below. System managers can trade off management effort, vulnerability, difficulty of installing new devices, difficulty of configuring clients, etc., to suit local preferences.

Types of Managed Devices

A managed device may or may not contain SENSE components.

  1. A device may contain no SENSE components, that is, both the SENSE Publisher and the SENSE Server are external to the device. An external Publisher may be responsible for more than one device.
  2. A device may contain a SENSE Publisher that publishes one or more Editions for the device.
  3. A device may contain both a SENSE Publisher and a SENSE Server. The internal server may be specialized to the device, that is, the Server may refuse to accept other Publications or other Editions for the device's Publication.

How many servers in a network?

The system manager can control, to a great extent, the configuration of SENSE Servers in the local network. The number and location of Servers can be controlled to trade off, for instance, the difficulty of installing new devices against the difficulty of installing new clients. (A tool for controlling the configuration is the Replicator Application, described below.) The SENSE network can be tuned to local needs, system management style, and network management style.

Below is a partial list of considerations in configuring a SENSE network.

Table 3: Some advantages and disadvantages of configuration strategies
Strategy: small number of servers; every Publication represented in every server.
Clients easy to configure: each client has one primary server, maybe one backup. Installing new device usually requires configuring Replicator as well as Publisher for device.
Servers can be concentrated on high availability or fault-tolerant systems. Concentrating all status information in a few servers requires thoughtful fault management.
Strategy: large number of servers. Extreme case is one server per managed device (Publication).
Easy to install new device. If device includes Publisher and Server, just plug in and run. If device includes Publisher only, then configure to publish in a specific Server. Hard to configure clients: client may have to search many Servers to find particular Publication(s) and Edition(s) of interest.
Failures have limited impact. Large number of objects in the network that require some management.

How do clients find servers?

Discovery of network objects is not a simple problem, and no single strategy is likely to be suitable for all situations. Most implementations may combine several strategies for finding servers.

The list below includes several possible strategies, from high tech to low tech, that might be useful to SENSE clients. (This list is only suggestive, not exhaustive.)

High technology is nice to have, but it requires a lot of network support and management. If some high tech solutions are not available in some configurations, or if high tech solutions need to be supplemented with simpler solutions that require less management, one can fall back to lower-tech solutions.

  1. Name Service. Adapt or establish conventions for storing the names of interesting entities. Publish the list of SENSE server addresses in the global name service, local name service, domain or cell directory service, whatever.
  2. Association: Some network entities may be associated with others in peer or hierarchical relationships. For instance, Servers might share information with other Servers, and therefore they might maintain lists of other active Servers.
  3. Advertising. Servers use a "service advertising" protocol, such as Novell SAP or similar, to advertise their presence and services offered. Clients listen for advertising messages from servers theyre interested in.
  4. Broadcast and Reply. Design a specialized broadcast message that SENSE clients and servers answer. This is the method used by the Mac Chooser to locate printers, namely broadcasting a "Hey, all you LaserWriters out there!" message. Similarly, the newly proposed "Service Locator Protocol" uses a specialized multicast message to which the appropriate servers respond.
  5. Systematic Ping. Algorithmically go through all "local" IP (or other network) addresses, asking if they have a SENSE server. This strategy is limited to servers on well-known ports, but that is probably not a serious limitation.
  6. Configuration Files. Put well-known files in well-known locations containing the addresses of servers. It is typical to have a hierarchy of files, ranging from shared file(s) maintained by a system manager to local file(s) on each client system.

Note that the information the clients seek can be either static or dynamic, that is, either the clients read statically defined information, or they actively solicit dynamic information from the network. Static information may come either from a central name service or from distributed configuration files. Dynamic information may come either from passively listening to the network or from actively asking the network.

The Replicator/Repeater Application

A SENSE Client application can be a Subscriber and a Publisher simultaneously. This feature enables two applications that permit unusual flexibility in configuring a SENSE network: the Replicator and the Translator.

The Replicator subscribes to Editions in one Server and publishes them unchanged in another Server, or in several other Servers. In general, a Replicator should reproduce all Editions for a Publication that it is replicating, but in some special circumstances it may be desirable to configure a Replicator to eliminate some Editions.

A Replicator can be used in two very different ways:

Replicators can be used by system managers to configure the SENSE servers in the network in very general ways.

The Translator Application

The Translator application subscribes to Editions in one Server and publishes them in a different form, in the same server, in another Server, or in several other Servers.

Translators can be used to produce specialized Editions for specialized monitoring applications, even though primary Publishers for those Editions may not be available for some devices.

How do Servers Deal with Multiple Network Protocols?

They don't. A SENSE Server uses only one network discipline at a time. That is, a SENSE Server may be capable of using IP, or IPX, or AppleTalk, but any instance of the Server is statically configured to use one network stack.

Appendix D:

The Server's Publication

Every SENSE Server contains a Publication that represents the Server itself, and publishes several Editions detailing events within the Server.

The Server Publication is distinguished by the following properties. See Appendix B for further details.

Table 4: Distinguishing properties of a SENSE Server Publication
Id.Host.NameThe network name of the computer system on which the Server is running.

Servers shall include the following properties in the Server Publication.

Table 5: Properties of the Server's Publication
Condition.CodeCurrent condition. See Appendix J.
Condition.TextTextual description of condition.
Condition.TimestampWhen condition last changed.
Id.ContactsysContact equivalent: Who manages this Server?
Id.DescriptionsysDescription equivalent.
Id.NameServer's administratively assigned name.
Id.ObjectIdsysObjectID equivalent for this SENSE server, specific at least to manufacturer and version.
Id.Host.AddressLocal host address of the node on which the Server is running.
- For IP host, dotted octet notation.
Id.Host.NameLocal host name.
- for IP host, fully-qualified internet name in dotted form.
Id.Host.PlatformPlatform descriptor. [[rules tbs]]
Id.InstalledDate when the Server was installed.
Id.LocationsysLocation equivalent for the node on which the Server is running.
Id.ManufacturerVendor/creator information, DMI equivalent, for Server.
Id.ModifiedWhen the Server contents were last modified, that is, when a Publication or Edition was last registered or unregistered.
Id.NamePlatform-dependent and network-dependent node name.
Id.ProductProduct name of the SENSE Server product.
Id.SenseVersionHighest version of SENSE comm protocol supported by Server.
Id.SerialNumberServer software serial number.
Id.StartedWhen the Server was restarted (booted, restarted by management command, or similar).
Id.VersionServer software version information, DMI-equivalent.

The Server Publication includes several Editions. All Servers shall publish at least the following editions.

Table 6: Required Editions of the Server Publication
Edition nameEdition Contents
Server.PublicationsEvents signifying the registration and deregistration of Publications in this Server.
Server.EditionsEvents signifying the registration and deregistration of Editions in this Server.
Server.AllAll events of importance to a SENSE Server: registration and unregistration of Clients, Publications, Editions.

Appendix E:

Editions of Publications

An Edition of a Publication is a specific format and subset of event messages relating to that entity. Generally, an Edition includes a specific type of opaque data and a specific set of properties that describe the event and the resulting condition of the entity. Together these two specifications describe the format of SENSE Event messages of this Edition.

Event Protocols are typed with respect to the syntax and content of the information conveyed within Event messages. Several protocols have subtypes that further delineate syntax and/or content aspects of the Event messages.

The official names of each Event Protocol described below are used as the keywords for the DATA property present in each Event message. In effect, these names serve as a classing mechanism that is typically used by a SENSE Client to distinguish among the various Event Protocols associated with a Publication Edition. Therfore, if an Edition is published in one of these protocols, the Publisher shall use the string given here as the first atom of the value of the Edition property Id.Name.

Event Protocol names are structured using the standard "dotted octet" form that provides a visual and processable form of class hierarchy. A collection of Event Protocols that compose a particular hierarchy are referred to as an "Edition set" in this document.

Table 7: Known Editions
CPAPCommon Printer Access ProtocolSpecification
CPAP.AcctAccounting Log
CPAP.EventLogEvent Log
CPAP.ShowStateShow State
SCSEPSimple CommonSENSE Event Protocol
SNMPSimple Network Management Protocol
SNMP.SETSNMP Set Response Messages
SNMP.V1.JobsJob Monitoring MIB
SNMP.V1.PrinterPrinter MIB (RFC 1759)
SNMP.V1.TRAPSNMPv1 TRAP Messagesbelow
SNMP.V2.TRAPSNMPv2 TRAP Messagesbelow
Server.EditionsEdition registration/unregistration
Server.PublicationsPublication registration/unregistration
Server.AllAll object and management activity within Server
STEPSimple Text Event Protocol
STEP.SingleLineSingle Line Textbelow
STEP.SingleLine.CCSingle Line Text with Condition Code
STEP.MultiLineMultiple Lines of Text
TIPSITransport Independent Printing System Interface (IEEE 1284.1)
TIPSI.CPMACommon Printer MIB/MIF Alerts
TIPSI.DSADevice Status Alerts
TIPSI.IMAInterpreter Message Alerts
TIPSI.JCAJob Control Alerts
TIPSI.OPAOperator Panel Alerts
etc. tbs

Appendix F:

Server Management Properties

The SENSE Server is also a manageable object in the network, and can be managed through the client management interface. After passing local security screens, a Manager Client can modify the properties and operation of the Server.

Properties of the Server object

Table 8: Management-related properties of the Server
Semantics of SET
Id.NameRWPost-it-note to supply Server with nickname.
Id..Location.NodeROFully-qualified network name of the node on which the Server is running.
Id.Location.PortRWNetwork port on which Server listens for Client requests. If zero, the Server uses the default port.
"On Write: If the new port number is different from the current value, close all current connections, delete all current registrations, listen for new connections on the new port number.
Server.RateLimitingRWTime in milliseconds between Server-emitted copies of Event messages.
Server.RemindersROBoolean value "T" or "F". Does the Server send reminder messages before Client registrations lapse?
etc. tbs

Appendix G:

The SNMP.TRAP Edition

Properties of the Edition

Table 9: Identifying properties of the Edition

Syntax of Opaque Data in Event Messages

For this edition, the opaque data in each event message is an SNMP V1 TRAP-PDU. The trap message should be precisely what would be delivered to a process by the UDP service on the client platform for a real SNMP TRAP message.

The TRAP message shall contain whatever fields are required by the NOTIFICATION-TYPE macro that defines the message for this type of trap. The cause of the trap, the TrapOID, etc., depend on the device and the event.

Properties Included in Event Messages

Publishers shall include the following Publication properties in every Event Message of this Edition.

Table 10: Properties included in event messages of this Edition
Condition.CodeintegerMost recent known condition of the Publication entity. See Appendix J.
Condition.TextstringText string representing the condition of the entity.

Publishers may also include other Publication and Edition properties in Event Messages.

Appendix H:

The Minimal Edition of a Publication

For some devices, it may be desirable to publish a minimal Edition of the Publication that reports changes in the overall "condition" of the device. Such an edition can be used for very simple green-yellow-red-light status monitoring applications.

Properties of the Edition

Table 11: Identifying properties of the Edition

Syntax of Opaque Data in Event Messages

The minimal Edition of a Publication contains no opaque data. The length of the opaque data region of the message is zero.

Properties Included in Event Messages

Publishers shall include the following Publication properties in every Event Message of this Edition.

Table 12: Properties included in event messages of this Edition
Condition.CodeintegerMost recent known condition of the Publication entity. See Appendix J.
Condition.TextstringText string representing the condition of the entity.

Publishers may also include other Publication and Edition properties in Event Messages.

Appendix I:

Server-Supplied Properties in Event Messages

The SENSE Server adds several properties to an Event message in an Edition when it forwards the message to Subscribers of that Edition. The Server includes enough identifying information that the Subscriber can uniquely identify the message source, and can recognize duplicate messages in the case of retransmissions.

Table 13: Properties added to every event message by the Server
Pub.IdintegerId number of the Publication on this Server.
Ed.IdintegerId number of the Edition on this Server.
Subs.IdintegerId number of the Subscription of the Client to this Edition
Msg.IdintegerSerial id number assigned to this message. The id is unique to this combination of Server, Subscription, and Event. If the same message is subsequently retransmitted, all the copies will contain the same id number.
Msg.TimestampdateWhen the Server sent this message to the Client. If the same message is subsequently retransmitted, each copy will contain the timestamp when it was sent by the Server.

Appendix J:

Condition Codes

The property Condition.Code contains a composite value that is encoded as described in this section. The condition code is a three-digit value that contains three sub-codes. In order from right to left, from least-significant digit to most-significant digit, the sub-codes represent Activity (values 0-9), Health (values 0-4), and Support (values 0-5).

Additionally, the three-digit general condition code may be prefixed with a vendor code. The format of vendor codes is vendor-specific. If a vendor code is present, all three digits of the condition code must be specified, including leading zeros, so that the general condition code and vendor code may be unambiguously distinguished.

[[more tbs]]

Table 14: Dimensions of Conditions
ActivityunitsCurrent level of activity, ranging from "idle" to "extremely busy."
HealthtensOverall operational status, indicating the relative severity of a problem, if there is a problem.
SupporthundredsLevel of technical training or support required to resolve the problem indicated.

Table 15: Summary of Condition Values
2UserWarning, transientNot idle
3OperatorWarning, persistentLightly busy
4TechnicianAlertBusier (see below)
5Administrator(reserved)Busier (see below)
6(reserved)(reserved)Moderately busy
7(reserved)(reserved)Busier (see below)
8(reserved)(reserved)Busier (see below)
9(reserved)(reserved)Extremely busy

The "Support" code describes the level of human expertise required to resolve a problem, ranging from basic familiarity with the device to trained hardware or software service skills.

Table 16: Possible values of "Support"
0UnknownUnable to determine the required support.
1NoneNo support required (entity should be healthy).
2UserVery low knowledge required.
3OperatorSome knowledge required, not necessarily technical.
4TechnicianSpecial training required, usually on the physical aspects of the entity; for example, Field Service personnel.
5AdministratorSpecial training required, usually dealing with software configuration, compatibility or interoperability; for example, System Manager.
6-9(reserved)Reserved for future definitions.

The "Activity" code describes the recent level of activity in the device, from idle to very busy. In many devices, there may not be sufficient history to evaluate this property in detail. If the Publisher does not have the data necessary to make find distinctions, it should indicate only that the device is "idle" or "not idle." If the Publisher has no data about device activity, it should indicate "unknown."

Table 17: Possible values of "Activity"
0UnknownUnable to determine activity level.
1IdleDefinitely no activity.
2Not idleSome activity is present, but unable to determine any kind of level.
3Low activityWthin the spectrum of ability to determine an activity level, this implies the least level of activity.
4,5Below-average busyMore than lightly busy.
6Average busyAverage level of activity; if the level of activity can be measured in some way, then this value represents the mid-point of the range.
7,8Above-average busyBusier than average.
9Extremely busyAs busy as the entity can possibly be without exploding, going on strike, or otherwise punting off into oblivion.

The "Health" code describes the ability of the device to continue processing without receiving attention or service.

Table 18: Possible values of "Health"
0UnknownUnable to determine the health of the entity.
1HealthyThe entity is capable of normal processing.
2Warning, transientThe entity is not capable of normal processing at the moment, but the condition should clear itself without assistance in a short period of time.
3Warning, persistentThe entity may still be capable of normal processing, but the condition will not clear itself without operator intervention.
4AlertThe entity is definitely not capable of normal processing, and the condition that prevents processing requires operator intervention.
5-9(reserved)Reserved for future expansion.

[[many examples tbs]]

Appendix K:

Classes of SENSE Objects

The Id.Class property of a Publication can be used to distinguish quickly the type of network entity that the Publication represents. This property is used in the ObjectGetFirst() API function to restrict the search to a particular class of Publications.

Table 19: Classes of Publications
/Sense/PrinterPublications representing printers, according to their Publishers.
/Sense/HostPublications representing computer systems on the network.
/Sense/Host/FilesystemPublications representing the file storage subsystem of a computer system on the network.
etc. tbs

SENSE objects other than Publications also use the Id.Class property to distinguish these objects in the ObjectGetFirst() function. Note that enumerating certain classes of objects, such as Clients, may be subject to security constraints in some implementations.

Table 20: Classes of other SENSE objects
/Sense/ServerThe Server Publication for this Server.
/Sense/PublisherAll Clients that have currently registered Editions in this Server.
/Sense/EditionAll Editions currently registered in this Server.
/Sense/ClientAll Clients currently registered with this Server.
/Sense/SubscriptionAll Subscriptions currently registered in this Server.
etc. tbs

Copyright (C) 1996 by Richard Landau & Jay Martin. All rights reserved.
Comments and flames to the authors. "Why use rational argument when there's a flamethrower handy?" Hey, go ahead. We didn't exactly leave the gloves on when we wrote this. Richard Landau ( & Jay Martin ( using that sterling tool, HTML Author. Last modified 96/05/19.