Procedure Vown(var msg: message_packet_type; snd: boolean;
               var stat: VI_status_type);
   EXTERNAL;
{*USER*
 
VOWN is used to declare those fields that the caller will "own".
Field "ownership" implies that the owner is responsible for controlling
the field and making sure that all connected tasks are kept up to
date with the latest changes.  The "owner" of a field makes the ultimate
determination of a fields value, and can modify that value unconditionally
as desired.
 
Ownership of a field controls the "echo" that is done when a new field
value is received.  This echo lets other programs receive the new field
value when it is changed by one program, keeping them all up to date.
There can only be one owner of a field.  If there are
two owners, a echo loop where one owner will echo the other owner's echo
without stop.
 
Ownership of a field will also "force" a message to be sent even if the
value in cache has not changed, since it is a assumed the "owner" knows
what it wants.
 
A message submitted to VOWN will be sent out normally to all
connected programs as it is
submitted to VSEND for cache entry and sending.  The only difference
is that the cache entry will be marked as "owned" by the calling program.
 
The processing status is returned in STAT.  If the boolean SND is
TRUE, the message is to be sent immediately to all connected jobs.  If
the boolean SND is FALSE, there are more messages coming (more VSEND/VOWN
calls),
and so the message may be buffered and sent later with the subsequent
messages.  Two constants are defined in VIEWPORT.PKG for use in SND.
They are VB_STILL_MORE (FALSE) and VB_SEND_NOW (TRUE).  It is recomended
that they be used instead of TRUE and FALSE in the VSEND call,
as they are more descriptive.
 
VOWN is the one of five commonly used VIEWPORT interface calls (VINIT,
VSEND, VRECV, VOWN and VDISC).  It will use the other VIEWPORT interface calls
for its work, making it uneccesary for the normal user to call any other
VIEWPORT interface calls.
 
The only accepted messages are field values updates (PK_FIELD_VALUE/PS_PUT).
Submission of any other message will be rejected.  The rules of cache
entry creation are the same as those of VSEND, as VSEND is used for the
cache entry creation.  VOWN needs to be called only once for a "owned"
field.  Multiple calls for the same field will accepted, however, remember
that only the first VOWN/VSEND defines the field size in cache.
 
 
*ERROR CODES*
 
VI_CHANGED - (PK_FIELD_VALUE/PS_PUT)
             Field value was placed in cache, and either the
             supplied value was different that the value
             already in cache, or this is the first time the
             value has been placed in cache.
 
VI_NO_CHANGE - (PK_FIELD_VALUE/PS_PUT)
               Field value was placed in cache, and the
               supplied value was the same as the value
               already in cache.
 
VI_NO_MEMORY - (PK_FIELD_VALUE/PS_PUT)
               Field value was not already in cache, and
               furthermore, we were unable to place the
               supplied field value in cache as there was
               no more memory available in cache.
 
VI_MSG_UNKNOWN - (PK_FIELD_VALUE/PS_PUT)
                 Message was not of type PK_FIELD/PS_PUT.
                 Ignored.
 
*WIZARD*
 
The actual behavior of this routine is to call VSEND to insure that the
cache entry is created, and then find the cache entry and set the
"ownership" boolean.  Since the ownership boolean is not set until after
the VSEND, the message will be sent ONLY IF the VI_CHANGED status
is returned.  If the status comes back VI_NO_CHANGED, the VSEND will
be invoked again, this time guarateeing the send since the "ownership"
boolean is now set.  In most cases, since ownership will be defined
at program initialization, only a single VSEND will be called with the
cache entry created during that call.
 
At this time, the SND parameter is ignored, and messages are always
sent immediately.  At some future time, "packed" messages will appear
and we will use those to pack multiple messages into a single
physical message packet for improved throughput and reduced
system overhead.
 
}