

                 XMPmsap library for Sun
                 =======================

1. What is it?

This library provides a link between the SunLink CMIP 8.1 XMP interface 
and the OSIMIS 4.0.6 system. It replaces the msap library used in the 
ISODE version of OSIMIS. The library implements the functionality of 
CMIS/P as described in the documents:

  - ISO/IS 9595 Version 2 "Common Management Information Service 
    Specification", 1991.
  - ISO/IS 9596 Version 2 "Common Management Information Protocol 
    Specification", 1991.

The CMIS API provided by the library is documented in msap/msap.3n.



2. How to use it?

2.1. Installation

You must have SunLink CMIP 8.1 XMP and OSIMIS 4.0 with patches 1-6 installed 
in your system. Compile the xmpmsap/libmsap.a library (./make) and use it 
instead of the msap/libmsap.a library. Make sure that the XMP/XOM system 
libraries are included by adding
 
	-L/opt/SUNWconn/lib -lXmp -lXom 

in the compiling options (e.g. by adding them to the value of LSOCKET in 
CONFIG.make).  Security and location transparency are not supported
(CONFIG.make switches SECURITY and LT).

You must also copy the file slots.xmp in the OSIMISETCPATH directory and 
change the isoentities file as follows:

1) The agent entries that will be used with the XMP should have 
   presentation addresses, for instance

   tel4 SMA      1.17.5.12.0   \"tp40"/"Prs"/"ses"/realNS=4972700d6401   

2) Also manager applications must have entries in the isoentities. 
   Examples:

   tel4 mngr1     1.17.5.14.1	\"tp41"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr2     1.17.5.14.2	\"tp42"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr3     1.17.5.14.3	\"tp43"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr4     1.17.5.14.4	\"tp44"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr5     1.17.5.14.5	\"tp45"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr6     1.17.5.14.6	\"tp46"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr7     1.17.5.14.7	\"tp47"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr8     1.17.5.14.8	\"tp48"/"Prs"/"ses"/realNS=4972700d6401
   tel4 mngr9     1.17.5.14.9	\"tp49"/"Prs"/"ses"/realNS=4972700d6401

   The second entry is formed from letters "mngr" and a running manager 
   number starting from 1 and running upward to 10. The addresses must
   match the configuration of the OSI stack.


2.2. Running OSIMIS based applications with XMP

The XMPmsap library is transparent to the user in normal operation.
In the case of crashing or otherwise misbehaving managers/agents it
can occur that some resources must be manually released. The resources 
in question are:

1) Shared memory used by the OSI protocol stack

   In this case you have to stop the osimcs daemon and deallocate 
   the shared memory using shmmgr. See SunLink CMIP 8.1 
   Administrator's Guide for details. 

2) The available manager numbers

   The management of available manager numbers in the same machine 
   is done by using an auxiliary file $OSIMISETCPATH/slots.xmp. 
   For each possible manager number there is a line 
   in the file containing ! or : and a number, for example:

		          !1
                          !2
                          :3

   Lines starting with ! are for numbers that are currently reserved while
   a line starting with : contains an available number.
   If the system runs out of manager numbers (through misbehaviour), the 
   numbers must be freed manually by changing the corresponding ! to :. 
   This can be done with an ordinary text editor (emacs for example).  


The file xmpgen.h contains a number of constants that determine the sizes 
of many statically reserved resources. Probably the most important ones
are _lifeSize and _lifeSize2 that determine the size of the memory pool
used for storing public XOM objects. These should be increased in the 
case of out of memory errors in om_malloc or mi_malloc.



3. Implementation notes

3.1. Original implementation for SunLink XMP version 8.0 

The main step in passing a message using XMP is building and sending the
corresponding XOM object. The strategy to build XOM objects 
is not the obvious one. All objects are formed as public objects. 
The reason is to make code as efficient as possible. 
To gain maximum efficiency objects are built in memory reserved from 
life time memory management. The actual building of XOM attributes is based on 
static constant template arrays. Each row contains a template for a possible 
row in an XOM result object. If the call parameter so specifies the row is 
included to the result. The resulting code is simple to read and 
relatively easy to maintain.

The conversion of incoming private objects to public ones is done by routine 
getArgument(), which also deletes the private object if second parameter is 1.
The internal handling of XOM objects is quite heavy, so it is avoided as much
as practical.

The library uses life time memory management. Memory is allocated from 
a statically reserved array with om_malloc() or mi_malloc(). The om_malloc()
routine is used in routines placed in moperation.c. The allocation should
only last for the duration of one XMP call. 
The mi_malloc() is used for incoming messages. 
The duration of allocation is intended to be relatively 
short, but it may extend over a period of several incoming messages. 
Each incoming message is placed in one life time group. The release is
on the responsibility of the caller (mi_free() is used for that purpose).


3.2. Changes in the implementation for the SunLink XMP version 8.1 

(The changes of the XMP stack have been documented in the
 SunLink CMIP 8.1 Programmer's Guide.)

There are two changes that require major modifications in the XMPmsap
library:

1) Major changes in OM class definitions

   In many OM classes certain attributes have been changed in the 
   following way: An attribute that used to consist of one or more 
   objects now consists of only one object which contains all the 
   previous objects. The construction of these objects is done by
   first building the object using the old syntax and then converting
   the object to the new syntax using the function deepen(). The 
   processing of these objects is rewritten to handle the new syntax 
   directly without using the old syntax.

2) Error handling

   Interface functions now return integer values instead of 
   OM private objects. Thus all error handling functions are
   rewritten.

There are also several changes requiring only minor 
or no modifications in the library. 

-the local-DN attribute in Object-Instance() is now a DS-DN 
 object, not a DS-RDN object
-In mp_receive(), the context object has been replaced in the parameter 
 list by the mode_return integer that was previously a part of the 
 context object. 


3.3. Avoiding the bugs in SunLink XMP version 8.1 

There is an error in the XMP header file. The values of 
MP_E_MISTYPED_ARGUMENT and MP_E_MISTYPED_OPERATION are switched.
This is fixed by redefining these constants with right values.

The timeout parameter in the mp_wait() function is not working as 
described in the manual. Luckily this doesn't affect our library.

If a process is trying to bind to an address already used, 
the XMP daemon will trash the shared memory. This is avoided by
explicitly allocating the addresses using the file slots.xmp. 




