
REPORT ON THE FULL PEPSY-BASED OSIMIS CONVERSION
------------------------------------------------

This is a short report on the conversion of OSIMIS to use only the
pepsy ASN.1 compiler and not a mixture of pepy/pepsy as in the past.
The rationale, the (minor) API changes required and the current status
are discussed.

RATIONALE
---------

OSIMIS used initially only the pepy ASN.1 compiler with hand-crafted
C structures to model the ASN.1 types i.e. the posy data structure
generator was never used. Pepy/posy were obsoleted by pepsy as the
ASN.1 compiler of choice as the latter produces much less code through
a table-driven instead of a recursive descent approach
and the encoding/decoding routines it generates are marginally faster.

New attribute/action/event report syntaxes in OSIMIS started to use pepsy.
The problem though has been that all the existing pepy-based ASN.1 types
could not be "imported" because of the incompatibility between the two.
Actually pepy syntaxes can import pepsy ones but not vice versa and
it is the latter case that is mostly needed. As a result, existing pepy
types were done again in pepsy, the problem being twofold:

1. additional amount of generated code
2. very different data structures to model the same ASN.1 type:
   a. a hand-crafted structure for the pepy version
      e.g. CMISParam for Attribute
   b. a automatically produced structure for the pepsy version
      e.g. type_CMIP_Attribute for Attribute

In order to fix those problems, a conversion has been necessary
trying to retain the existing API as much as possible.


TECHNICAL APPROACH AND API CHANGES
----------------------------------

The pepy hand-crafted msap/msap.py CMIP ASN.1 file was converted to use
pepsy. The agent/gms/SmiAsn.py (pepy-based) and the agent/gms/Smi2Asn.py
(pepsy-based) files were merged to agent/gms/SmiAsn.py which now uses pepsy.
In order to achieve the conversion, some minor API changes were necessary.

A lot of #define'd tags have now different values but this should not
be a problem as far as software uses them properly e.g. does not assume
zero default values and uses calloc or bzero to "initialise" structures.

Some rationalisation of the CMIS API data structures in mparm.h was
necessary. As such, the CMISClassInstanceConflict structure is now
called CMISBaseManagedObjectId. The previous structure name and field
names have been #define'd to the new ones for backwards compatibility.
The CMISParam structure is now used instead of CMISInvalidAttributeValue
with #define'd field names to the new ones for backwards compatibility.
The only non-backwards compatible change in the CMIS API is that there
is no CMISMissingAttributeValue structure anymore as the MIDListVal one,
which models the ASN.1 type AttributeIdList, is now used.
In the agent part this is hidden by the GMS while in the manager part
it is hidden by the RMIB, so it should not be a problem in general apart
from managers using directly the MSAP CMIS API.

The only important API change has to do with the name of the
type_SMI_StringList structure in SmiAsn.h which is now called
StringListVal while its string member is called string instead of IA5String.


PLEASE NOTE:

If you have used the SMI-types.h data structures in version 3.3 and in
particular the type_SMI_AlarmInfo and type_SMI_ObjectInfo, you will
have to change the way AttributeId, Attribute and AttributeList corresponding
structures are addressed:

instead of type_SMI_AttributeId, type_SMI_Attribute and type_SMI_AttributeList
you should use MIDentifier, CMISParam and CMISParamListVal.

If you do not do that, you will get a core dump. For example, iterating
through the attributes of a type_SMI_ObjectInfo structure should be done
as follows:

    Attr* report = ...;
    type_SMI_ObjectInfo* objInfo = report -> get();
    CMISParamListVal* attrList = (CMISParamListVal*) objInfo -> attributeList;

    while (attrList) {
	// do something with mpl_id / mpl_val
	attrList = attrList -> mpl_next;
    }

This is true for any other current or future structures containing
those types. Also char* is used for strings instead of the ghastly
struct qbuf pepsy generates. Printing for example the additionalText
of a type_SMI_ObjectInfo structure is done as follows:

    char* addText = (char*) objInfo -> additionalText;
    if (addText)	// optional...
	printf("%s\n", addText);



REMAINING ISSUES
----------------

The following aspects need further work:

1. pepsy does NOT check the range of enumerated types, so any enumerated
   attributes should enhance either the decoders registered in oidtables
   e.g. as in SmiSntx.c or the virtual decode method of the relevant
   C++ attribute to be safe - the former method is better as the check will
   be available at the managing end as well

   this has NOT been done yet for the SMI attributes

2. pepsy cannot cope with the CreateArgument superior instance ASN.1 syntax;
   a workaround is currently used which will prevent interoperability
   with other platforms if the superior instance option is used for
   object creation
   
3. pepsy cannot cope with the (untagged) "actionType ActionTypeId"
   choice element of ActionErrorInfo, so a tag [2] was added but will
   prevent interoperability; this is the case only for noSuchAction
   error in linked replies

   a similar problem, it is not easy to have pepsy "tell" you if a SET OF
   OPTIONAL parameter is empty i.e. {}; this means that the "no attrs"
   option of GetArgument cannot be provided in a standard way; again, a
   non-standard extension is currently used which may prevent interoperability
   with other platforms when this option is used

Both above problems can be fixed by hand-coding as is the case very often when
converting pepy -> pepsy, but time was not available to do this at present.


