Rectifying the use of M-Action in OSIMIS 3.5
--------------------------------------------

OSI management actions can be thought as arbitrary remote method
calls on distributed managed objects. Parameters may be passed
with the action request (remote method call "argument(s)") while
results may be returned with the action reply (remote method call "result(s)").
The arguments and results have to be specified each as a single ASN.1 type
which is associated to the object through the INFORMATION SYNTAX and
REPLY SYNTAX GDMO clauses respectively (see ${TOP}/examples/odp/MIB.gdmo).

As OSIMIS uses the $(OSIMISETCDIR)/etc/oidtable.at to associate a
name/object identifier to a syntax, actions have to be handled in the
same way. This poses a problem an an action may have two ASN.1 syntaxes
associated with it (information/reply) while oidtable.at allows only ONE
syntax per name/OID. The trick that was used up to now to get round
this limitation of oidtables was to specify a new syntax which was
the untagged CHOICE of the information and reply ones. This exploits
the fact that all the OSI encoding rules (BER, LWER etc.) encode
an untagged CHOICE exactly as its contained items.

This solution is far from satisfactory as it will most probably require
a new ASN.1 type for most of the actions even if the information/reply
syntaxes are already supported in OSIMIS. For example, for 
information syntax GraphicString and reply syntax REAL, the following
syntax is needed:

GraphicStringOrReal ::= CHOICE
    {
    string      GraphicString,
    real        REAL
    }


In OSIMIS-3.5 this limitation is lifted in the following fashion.
An action name is now registered in oidtable.gen instead of oidtable.at
without any associated syntax. The information and reply syntaxes
are registered in oidtable.at with names <actionName>Info and
<actionName>Reply and OID suffixes 1 and 2 respectively. For example:


# 2 Action(s) (oidtable.gen)

calcSqrt:       uclAction.701
calcMeanStdDev: uclAction.702

# 2 Action(s) Info/Reply Syntax(es)
(oidtable.at)

calcSqrtInfo:   uclAction.701.1 :Real
calcSqrtReply:  uclAction.701.2 :Real

calcMeanStdDevInfo:     uclAction.702.1 :RealList
calcMeanStdDevReply:    uclAction.702.2 :RealList


The above is a section of the oidtable.tmp as produced by the GDMO compiler
for the simpleStats class of the ODP server/client example
(see ${TOP}/examples/odp). Actually those two actions have the same
information and reply syntax and do not benefit as such from the new
scheme but they are shown just to demostrate the case.


Some changes to the programmatic OSIMIS API is now needed to handle
this ammendement. First, the str2ava and ava2str encoding/decoding
primitives will not work with the action name. As such, for
actions the str2ava_info/str2ava_reply and ava2str_info/ava2str_reply
should be used instead. These are macros defined in ${TOP}/msap/msap.h
calling the str2ava_aux and ava2str_aux new primitives.

When the user constructs a AVA type to be passed to the RMIBAgent::Action
method, the following options are possible
(see ${TOP}/examples/odp/OdpTestClnt.cc as an example):

    // using the actual syntax object e.g. Real

    actionArg = new AVA("calcSqrt", new Real(atof(argv[2])));

    // using the AnyType option for the value
    // note the different name used for setting-up the AnyType

    actionArg = new AVA("calcSqrt",
                         new AnyType("calcSqrtInfo", argv[2]));

    // using the plain string option for the value (not recommended though)

    actionArg = new AVA("calcSqrtInfo", argv[2]);
    actionArg -> adjustActionOid();

Basically if the AnyType option is used, the "<actionName>Info"
name should be used instead. If the plain string option for the value
is used in conjunction to "<actionName>Info" (not recommended but
nevertheless available for flexibility), the encapsulated OID should
be adjusted back to that corresponding one to "<actionName>".
If you forget to adjust it, a noSuchAction CMIS error will be received
as "<actionName>Info" is only a convenience not seen "on the wire"
i.e. the GDMO class does not know about it.


In general, you should better use the first option as it is more efficient
due to the absence of an oidtable search. In OSIMIS versions < 3.5,
you will have to link libgms.a with managers in order to do that as
libsmisntx.a did not contain the syntax classes. This has now been changed
and libsmisntx.a contains also the syntax classes (libgms.a does not anymore).

