Conference azur::mcc

Gene -- Your best bet is to copy In-Entity to Out-Entity before performing
the Call_Access

/keith

    Yeah, that is what I am doing, but the problem is more complex than
    that, asspecially if we are talking about building MCC Message after
    the mcc_call.
    
    The problem here that if I will pass to AM the wrong In-Entity,
    assuming that this entity is good enough for dispatcher to deliver it
    to proper AM, but AM is not happy with it, it may raise an exception.
    Whithout setting Out-Entity inside of AM, the resulting combination
    of Out-Entity = In-Entity, Verb and Exception may have no
    correspondence in the dictionary, and as result the PM won't be able to
    interpret the corresponding MCC Message.
    
    Gene
    
    

>    The problem here that if I will pass to AM the wrong In-Entity,
>    assuming that this entity is good enough for dispatcher to deliver it
>    to proper AM, but AM is not happy with it, it may raise an exception.
>    Whithout setting Out-Entity inside of AM, the resulting combination
>    of Out-Entity = In-Entity, Verb and Exception may have no
>    correspondence in the dictionary, and as result the PM won't be able to
>    interpret the corresponding MCC Message.

o What do you mean by "pass the AM the wrong In-Entity" ?

  I assume you mean the wrong name or datatype?  But the Class codes
  are correct (?)

  What kinds of probems are you having ?

  If you supply a "Good enough for dispatcher" In-Entity, and copy it
  to Out-Entity ... and DECnet AM is not happy - does Out-Entity get
  corrupted in anyway?  Isn't it the same Out-Entity you put there before
  your call?  Shouldn't the MCCMessage be processed properly then?

-----

The SRM says - The Caller need only provide Out-Entity in one of the
following cases:

  o A wildcard was used in In-Entity
  o The caller needs to see the Out-Entity (such as the case where other
    than the primary identifier was specified in In-Entity)

The Ultrix RPC model requires you to supply an Out-Entity (you can't
just pass a NULL) -- 

fwiw: The Design Framework already provides logic in your MM to help process
      the DECmcc Call Interface; the Init-handle-first/more/cancel and
      end_directive/update_call_handle routines.

      In a future release, the 600 or so lines of code which you must
      replicate, will be replaced with a subroutine call !!  All the
      redundant knowledge which each MM must know will be removed from
      your code.  Likewise, it is my intention to provide such a library
      routine to front-end the DECmcc Call from the FM/PM level.  To
      make the interface simpler, and make sure the arguments are set up
      properly.

/keith

Keith,

Maybe it is a little bit on nitpicking side, but I see the problem as follow.

We assume that dispatch table and dictionary are in sinc, so no problems here.
The problem may lay with the fact that the same entry point in dispatch table
may serve more than one VEA tuple. As result the module may do some internal
dispatching, determines that it is not happy with the entity which it interprets
as say entity of the class A, and raises the exception E. The PM may decide that
this entity is of the class B. In dictionary we have the exception E for entity
A but not for entity B.

This may happen when one entity is a child of another.

To give you a real example:

	MCC> show node4 tutu remote node tutu

Here the entity is: "node4 tutu remote node tutu"

The exception 

	Node does not exist or is not known to local Node.

is actually belongs to entity node4.

Beacuse when I issue the command

	MCC> show node4 diehrd remote node tutu

where "diehrd" is the real node, the response is

	No such entity: 
	                         Unknown Entity = 

which is appropriate for the entity: "node4 diehrd remote node tutu"

That is the exception which I expect to have for the entity
"node4 tutu remote node tutu" too.

The problem is masked here because for node4 and all its children the
corresponding .MS files looks like that:

	....
	include SHOW.ms;
		 END DIRECTIVE SHOW;
	...

for each of the entities, where SHOW.ms looks like that:

	(* Management Specification for DNA Phase IV, SHOW Directive
			General SHOW Directive for DNA Phase IV Entities. *)

	DIRECTIVE SHOW = 1 :
		...
		(* Begin Exception Definitions  *)

	INCLUDE mcc_dna4_am_common_exceptions.ms;

		(* Any specific exceptions for this directive follow:	*)

		(* NOTE:

		   END DIRECTIVE Show; - removed to allow additional exceptions 
		   to be declared in host file

		 *)

To best of my knowledge there is no specific exceptions for any of the children.

But if we assume that exception "Node does not exist or is not known to local
Node." is declared specifically only for node4 entity, than in this case this
exception won't be recognized for "node4 remote node" entity.

BTW, I don't know how PhaseIV AM operates internally and whether the same
routine serves entity node4 and entity "node4 remote node" but I have feelling
that the proper exception for the entity: "node4 tutu remote node tutu" should
be either "No such entity" or "Node does not exist" but passed as the MCCMessage
if AM first tries to access the entity "node4 tutu".

Best regards,
Gene

> does Out-Entity get corrupted in anyway? 
> Isn't it the same Out-Entity you put there before

Thank you, at least I don't have that.

    Gene,

    I think there are a few problems here:

    	1) What to do with the Out-Entity parameter when you call another
           Management Module ?

    	2) How does the MCCMessage Datatype work ?

    	3) How the DECnet phase-4 AM handles an unknown entity ?

    If you don't mind - I will try to answer these as three separate
    replies.

    /keith

    RE: .0

    1) What to do with the Out-Entity parameter when you call another
       Management Module.

    IMHO - The DECmcc Call interface is a bit too complex - I'd like to see
    it made simpler; or at least the detail hidden by a library routine 8)

    I had suggested that you, as an FM writer, build your In-Entity
    parameter and copy it to Out-Entity before calling the Access Module. 
    This is simple and works every time  8)

    However, the SRM states that Out-Entity is *optional* under certain
    conditions ...

    SRM 11 mcc_call

         If entity wildcarding is used for any entity level of
         In-Entity for an operation that returns data for each entity,
         this argument is required.  If no wildcarding is used in the
         In-Entity argument, or no returned output data is expected
         that neeeds qualification by entity and child entity, this
         argument is optional.  If it is provided, the service
         provider must write the fully qualified entity into it.

         If this argument is not provided by the client, this argument
         should contain a NULL (value = MCC_K_NULL_PTR) pointer.  If
         this argument is NULL and the service provider does require
         this argument, the condition value MCC_S_NOOUT_ENT is
         returned by the service provider to the client.

    So - If Out-Entity is optional, then you have to *know* where to look
    for the entity specifier .. Should I look at In-Entity, or Out-Entity?
    I'd prefer to write my code to always look in Out-Entity; copy
    In-Entity to Out-Entity before the call, then always look in Out-Entity
    when processing the output data.

    There could also be some problems with the "MCCmessage" datatype,
    should Out-Entity not be processed correctly -- See the next reply.

    /keith

    RE: .2

    2) How does the MCC-Message Datatype work ?

    SRM 9.4.9 MCCMessage

        "The MCCMessage data type is used to encapsulate user
         information about a request and its reply returned by a
         mcc_call call.  This data type is used as an argument to an
         exception or to a response, especially in the case where the
         management module wants to report an inability to complete a
         request due to the failure of a required service.  The
         MCCMessage data type may not be used as the data type of an
         identifier attribute."

            :
            :

    ----------------------------------------------------------------------

    What is actually used by the MCCMessage datatype? (from the
    mcc_interface_def.h file)

         typedef struct _MCC_R_Mesg_List {
           unsigned short int   mesg_w_count;
           unsigned short int   mesg_w_id;
           MCC_T_CVR           *mesg_A_CVR;
           unsigned long int   *mesg_A_Directive;
           MCC_A_AES            mesg_a_out_Entity;
           int                 *mesg_a_out_P;
         } MCC_R_Mesg_List;

    You build *your* exception which says that you couldn't complete your
    operation -- due to a problem with an MM which you called.  You can
    easily (and probably should) use the Common Exception 'Cannot
    Complete'.  One of the arguments to your exception is the MCCMessage,
    and contains the information from the structure above.  The PM that
    processes *your* exception will open up the MCCMessage and process the
    data within:

    'mesg_A_CVR' determines if there is a reply (response or exception)
    built into 'mesg_a_out_P'.  If it is a response or specialized
    exception, the 'mesg_A_Directive' and 'mesg_a_out_Entity' will be used
    to access the Dictionary and process the reply.

    The interesting part -- if the MM that provided you with these
    parameters didn't get the opportunity to copy or otherwise specify the
    proper contents of Out-Entity, your MCCMessage will be useless as the
    Out-Entity is used as a key into the dictionary -- and thereby cause
    some kind of difficulty for the PM processing *your* exception.

    /Keith

    RE: .4

    3) How the DECnet phase-4 AM handles an unknown entity ?

    One of the goals of the Phase-4 AM was to provide simple and meaningful
    error message to the user -- the team did a very nice job.  But when it
    comes to writing an MM which can understand the replies from another MM
    it gets tricky.  If you are writing a *generic* MM it is even more
    interesting.  There needs to be a good balance if DECmcc is to be
    successful.

         Maybe MM's should return *two* types of replies; the
         user-friendly message *and* a generic message for other MM's
         to processes generically -- subject of another note  8)

    Currently, the Phase-4 AM returns a specialized exception should the
    global entity (node name) be unknown:

    	Show node4 tutu all ident
    	Node does not exist or is not known to local Node

    Friendly and meaningful enough  8)

    But, if a child entity does not exist, the Phase-4 AM uses the Common
    Exception: No Such Entity

    	Show node4 diehrd remote node tutu all ident
    	No such entity: Node4 molar Remote Node tutu

    The Common Exception was used correctly.  I believe your concern is
    that it should also be used when the Global Entity is unknown also.


    >>> More about the 'No Such Entity' Common Exception

    The 'No Such Entity' Common Exception takes an argument; the unknown
    entity; the proper use of the argument will tell you exactly which
    entity is unknown.  The V1.1 Sample AM did not process the 'No Such
    Entity' Common Exception proper, but has been fixed in V1.2:

    	Show Sample tutu all ident                | Unknown Global Entity
    	No such entity: Sample tutu               |

    	Show Sample tutu line blah all ident      | Unknown Global Entity
    	No such entity: Sample tutu               |

    	Show Sample diehrd all ident              | Ok
    	...                                       |

    	Show Sample diehrd line blah all ident    | Unknown Line Entity
    	No such entity: Sample diehrd line blah   |

    /keith

    I QARed the description about out-e in the SRM long ago.  Out-e is
    *not* an output argument, as stated.  If it were, it would have to be a
    double pointer (caller specifies where the output AES should be stored,
    or NULL if he doesn' want it).  In fact, out-e is a "modify" parameter
    (like handle).  It must be setup by the caller and changed by the
    service provider if necessary.   Whether or not you agree with this 
    (I don't) is moot since changing to a double pointer would invalidate
    tons of existing code and is not likely to ever be done.
    

Keith,

You are absolutely right to separate the problem into different topics.
The only reason why they appear together is that I've wanted to show on some
real and hypothetical examples what is and may be the problem with Out-Entity
parameter.

The original question was and still is:

    When I am using mcc_call functions what should I use for the OUT_ENTITY
    parameter and what is the responsibility of the called module in setting it
    in case of the common or specialized exception?

>    IMHO - The DECmcc Call interface is a bit too complex 

You bet, without this note file and your help and persons like you we simply
won't be able to do anithing. Thanks again.

>    or at least the detail hidden by a library routine 8)

The only things which are hidden right now are the description of the parameters

>    I had suggested that you, as an FM writer, build your In-Entity
>    parameter and copy it to Out-Entity before calling the Access Module. 
>    This is simple and works every time  8)

"This is simple and works every time". That is the statement about which I am
not so sure. That the reason why I have provided reply .4 with examples.

So may I ask one more time:

    What is the responsibility of the called module in setting Out-Entity
    in the case of the common or specialized exception when Out-Entity has
    been provided by calling module.

Gene.

re: .10

>    What is the responsibility of the called module in setting Out-Entity
>    in the case of the common or specialized exception when Out-Entity has
>    been provided by calling module.

You know - that's a good question!  The Toolkit Design Framework has
you (as the Called Module) always copy In-Entity to Out-Entity during
the 'init_handle_first' routine.

So if something screws up along the way, Out-Entity will be set.  This has
always been the technique that I have used for my Management Module.

But, you probably want to know where this tib-bit is written down -- I guess
the rules are pretty much the same as if the MM was returning a Response.

--> the MM has a common or specialized exception:

  (1) If Out-Entity is undefined, don't do anything
  (2) If Out-Entity is defined, and you have a Primary
      Identifier to return, copy the Primary Identifier to Out-Entity

  Hopefully, the caller put a valid entity-spec in Out-Entity when they
  called you.

I believe this is what the SRM would have you do -- but, you as an FM
could return the AM's reply in an MCCMessage...the MCCMessage wants to
encode an Out-Entity .. if you didn't provide an Out-Entity when
you made the call the MCCMessage will be built improperly.

Whew -- Yuck -- Please, just copy In-Entity to Out-Entity ... 8)

/keith