
                  OSIMIS CHANGES IN ICM RELEASE 3.3

This document outlines the changes in the ICM OSIMIS release 3.3 mainly
since the release 3.2 but also since the last public domain release 3.0,
with emphasis placed in the non backwards-compatible ones. It should be
noted that the latter have been kept to a minimum. Important additions
are also mentioned but this document does NOT serve as a manual for those.

This document should be read very carefully before converting previous
code to work under 3.3 and its guidelines should be followed to the letter.



ATTRIBUTES
----------

The Time class in $(TOP/agent/gms/SmiAttr.h holds now the time internally
as a string of the form e.g. "940325180000Z" instead of UTCtime*
(or simply UTC). This does not affect the existing interface to the class
apart from the methods "int set(void*)" and "void* get()" which now
accept and return respectively a char* . This is a 3.0 -> 3.1 change.

The "Switch set(double)" method of the Gauge class has now become
"Switch setreal(double)" to overcome the strictness of the ATT C++ compiler
as there is an inherited "int set(void*)" virtual method which expects
an ObservedValue* argument.


In OSIMIS version 3.0, attribute filtering was possible by redefining
the "Bool filter (int, void*)" polymorphic method of the Attr class.
In all the later versions this is done by redefining only the
"int _compare(void*, void*)" polymorphic method for the ASN.1 type
as this minimises the code required.  The old mechanism is still supported
but its use is discouraged. This is a 3.0 -> 3.1 incremental addition.



GDMO COMPILER
-------------

The buildReport method
----------------------

As the object and state management notifications are now automatically
supported without the need of a buildReport polymorphic method, the GDMO
compiler does NOT automatically produce a declaration in the <moclass>.h
file. If a class has other notifications in addition to objectCreation,
objectDeletion, attributeValueChange and stateChange, then the user has
to declare manually in <moclass>.inc.h the buildReport method in the protected
region i.e.

// ...
protected:
    int		buildReport (int, int, PE*);
// ...

The reason for this is that for most classes those notifications are
all they have and the user should define a dummy buildReport method
calling the Top class one in order for the program to link successfully.
This is also in line with the policy for the future notification API
in which buildReport will not exist (see [1]).


Compiling inheritance trees of depth > 2
----------------------------------------

Please also make sure that the whole inheritance tree for classes you
compile is in the same file (apart from top) as if this is not the case
the GDMO compiler will produce wrong information which will only manifest
itself at run-time.


The createRR, deleteRR methods
------------------------------

Early versions of the GDMO compiler scripts in OSIMIS 3.1 produced
<moclass>::create and <moclass>::cmisCreate methods which called
automatically the createRR method for the class. This is not the case
anymore since version 3.2 for various reasons.

When a managed object is created or deleted as a result of interaction
with a real resource, these methods should be explicitly called by
the implementor. An example taken from the OSI TP MIB in
$(TOP)/agent/isode_mib:

    transportConnection* tpConn =
		transportConnection::create(str2rdn(id), _tpEntity);
    tpConn -> createRR();
    tpConn -> triggerObjectCreation();

    // ...

    tpConn -> deleteRR();
    tpConn -> triggerObjectDeletion();
    delete tpConn;


Attribute default values
------------------------

The GDMO compiler produces now an "empty" default value for attributes
with a SET-DEFAULT property. You will need to set the default value
in <moclass>::initialiseClass only if you want another default value.

Note: default values present in the GDMO are currently ignored.



DISTINGUISHED NAMES
-------------------

To convert a string to a distinguished name please use the
"MN ObjectInstance_parse(char*) method" declared in $(TOP/agent/gms/SmiSntx.h .
This will return a MName* (or simply MN) which states if this is a global
or local name. Global names start with c=, countryName= or systemId=
while local names with anything else.

If within an agent application you want to convert a name to local,
please use the "DN  CMISAgent::mn2localdn(MN)" method. The CMISAgent
single object instance can be obtained as:

    CMISAgent* agent = CMISAgent::getInstance();



ALLOMORPHISM
------------

Allomorphism was supported in version 3.0 but not in versions 3.1 and 3.2
after the GDMO compiler was introduced. It is supported again in version 3.3
through the "int Top::addAllomorphicClass(OID)" method which should be
called in the <moclass>::initialiseClass one.

An example from the UNIX MIB in $(TOP)/agent/ux_mib/uxObj2.inc.cc:

    addAllomorphicClass(name2oid("uxObj1"));



CHANGES IN GENERIC (SMF) CLASS NAMES
------------------------------------

The discriminator and event forwarding discriminator classes are
now called discriminator and eventForwardingDiscriminator respectively
as they are produced automatically by the GDMO compiler. This change
should not affect code as these classes are "invisible", being hidden
by the GMS and RMIB infrastructure.

The only thing affected though is the <Sma>.h file for every agent as
it should include now "eventForwardingDiscrminator.h" instead of "Discr.h".
In general, the Sma.h and Sma.cc files from $(TOP)/agent/sma should
be adopted as the basis for every specific agent application files
in every new OSIMIS version. The specific <Sma>.h should have the
basic parts relating to the SMFs and the MIT-top system while the
<Sma>.cc should be a strict superset of $(TOP)/agent/sma/Sma.cc .



OBJECT AND STATE MANAGEMENT NOTIFICATIONS
-----------------------------------------

The objectCreation, objectDeletion, attributeValueChange and stateChange
notifications are now automatically supported by the GMS for changes
through the management interface (CMIS). A number of user-friendly
primitives are supported to trigger those notifications because of real
resource activity (see [2] and also $(TOP)/h/Top.h).

Ideally you should use those and avoid defining the buildReport method
for those notifications as this will result in less code. You may though
leave the code as it is and do the former later as the general notification
API remains exactly as it was.

Note: the oldValue optional argument of the triggerAttributeValueChange
      and triggerStateChange primitives is a PE which when supplied needs
      to be free'd by the user;
      an example from the monitor metric MIB in $(TOP)/agent/monmet_mib:


      PE oldStateValPE = pe_cpy(scanner::_attrs[I_operationalState]->encode());
      ((OperationalState*) scanner::_attrs[I_operationalState])
                        			-> set(os_disabled);
      triggerStateChange(I_operationalState, scanner::_level, oldStateValPE);
      pe_free(oldStateValPE);



THE REMOTE MIB ACCESS API
-------------------------

A very limited RMIB implementation existed in OSIMIS 3.0, comprising only
a high-level event reporting interface. A full synchronous-only RMIB API
appeared in version 3.2 .

The 3.3 version supports now fully asynchronous services, but the following
non-backwards compatible changes were introduced:


The RMIBAgent receiveEvent/stopReceiveEvent calls are now

    int     receiveEvent (char*, char*, char*, char*, RMIBManager*);
    int     stopReceiveEvent (char*, char*, char*, char*, RMIBManager*);

An additional char* fourth argument has been introduced to allow
assertions on eventTime (see the RMIB API manual for its use).


The RMIBManager eventNotification callback is now

    int eventNotification (char*, char*, char*, char*, Attr*, RMIBAgent*);

where the last argument indicates which RMIBAgent the event report
originates from.


Finally, all the low-level RMIB interface calls are now taking MN instead
of DN for the object instances.



MONITOR METRIC OBJECTS
----------------------

OSIMIS 3.3 contains an implementation of (some of) the metric objects of [3].
These are particularly useful to enhance "raw" management information
and they obviate the use of rates, counter/gauge thresholds, tide-marks and
the qualityofServiceAlarm in the management information model.
Jim Reilly provided an description in [4] regarding their functionality.

The current implementation contains also a counterOrGaugeDifference
attribute for the monitorMetric class whose value can be initially
supplied to determine if a difference should be taken from the observed
counter or gauge (False is the default value i.e. no difference).
As such, a counter can be observed as is or be converted to a rate
while a gauge can be similarly observed as is or be converted to
a derived gauge. The reason for this non-standard attribute is that
OSIMIS does not yet support packages properly - there are
counterDifferencePackage and gaugeDifferencePackage in the GDMO specification.

Another non-standard addition are maximum and minimum tide-marks associated
with the severityIndicatingGaugeThreshold and
estimateOfMeanSeverityIndicatingGaugeThreshold attributes respectively
as they provide useful additional information.



THE GENERIC CMIS/P to SNMP PROXY (INTERNET Q-ADAPTOR)
-----------------------------------------------------

This is now complete, you may consult [5] on how to set it up.



THE UNIX MIB
------------

The functionality of the previous uxObj1 class has now been split
in two classes, uxObj1 and uxObj2, the later inheriting from the former.

The uxObj1 class does not have the gauge threshold and tide-mark attributes
and as such it implementation is very simple through a "fetch-on-request"
only update policy. The uxObj2 class adds the gauge threshold and tide-mark
and the qualityofServiceAlarm notification through a periodic polling scheme.

The reason for this split is that the functionality of uxObj2 (and much more)
can now be generically provided by a monitor metric object.

Also the uxObj1Id naming attribute has now been re-named to uxObjId to be more
generic and serve to name other possible UNIX-related classes.



THE OSI INTERNET MIB
--------------------

The top MIT object of this MIB was in the past of class systemOIM which
is named simply system in RFC 1214 [6] but is different to the ISO system.
As such, new name bindings for SMF objects to systemOIM were needed
for every object with an ISO system name binding.

The ISO to Internet Management Coexistence (IIMC) work [7] has changed
that and now the systemOIM class is called internetSystem and resides below
the ISO system in the MIT, in parallel to the other Internet related
top-level objects (e.g. interfaces, ip, tcp etc. for MIB-II).

Despite the fact that the OIM-SMA application in OSIMIS has not yet been
updated to reflect the IIMC work, it schema with respect to the systemOIM
object has changed as above. Local distinguished names for all the other
classes remain as before with respect to the MIB schema.

Also all the empty string relative distinguished names e.g. ipId=""
have now become NULL strings e.g. ipId=NULL . This is because the double
quote character is not part of the GraphicString set and the latter is
the correct type for names (see SimpleNameType in [8]) - the empty
double quote name was an ill-conceived idea in RFC 1214.



References
----------

[1] Pavlou, G., "OSIMIS APIs: Past, Present and Future", February 1993,
    OSIMIS document in $(TOP)/doc/apievol.txt

[2] Pavlou, G., "A Model for Realising Object and State Management in OSIMIS",
    February 1993, OSIMIS document in $(TOP)/doc/objmgmt.txt

[3] ISO/IEC 10165-11 "Information Technology - Open Systems Interconnection -
    Structure of Management Information - Part 11: Metric Objects
    and Attributes (formerly Workload Monitoring Function)", March 1993

[4] Reilly, J., "Monitor Metric Objects and Attributes", February 1993,
    OSIMIS document in $(TOP)/doc/monitor.txt

[5] McCarthy, K., "The Internet Q-Adaptor (OSI->SNMPv1) Release 1",
    March 1993, OSIMIS document in $(TOP)/doc/iqa.txt

[6] LaBarre, L., (Editor), "OSI Internet Management: Management Information
    Base", RFC 1214, April 1991

[7] LaBarre, L., "ISO/CCITT and Internet Management Coexistence (IIMC):
    Translation of Internet MIBs to ISO/CCITT GDMO MIBs", October 1992

[8] ISO/IEC 10165-2 "Information Technology - Open Systems Interconnection -
    Structure of Management Information - Part 2: Definition of Management
    Information", January 1992

