Procedure Vsend(var msg: message_packet_type; snd: boolean;
                var stat: VI_status_type);
   EXTERNAL;
{*USER*
 
Process a message MSG to be sent to all connected forms.  Regardless
of whether there are any connected forms, update cache if needed to reflect the
sent value.  Return processing status in STAT.  If the boolean SND is
TRUE, the message is to be sent immediately to all connected forms.  If
the boolean SND is FALSE, there are more messages coming (more VSEND 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.
 
VSEND is the one of four commonly used VIEWPORT interface calls (VINIT,
VSEND, VRECV 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.
 
Whenever the user wishes to initialize or update a field value
to reflect a new value (using PK_FIELD_VALUE/PS_PUT),
the VSEND routine should be used.  Not only will the current value be
updated (or added) in the field value cache, but the value will be sent
to all form jobs in the "connected form list".
 
Messages other that a field value update (PK_FIELD_VALUE/PS_PUT) will
be accepted, and sent to all form jobs in the "connected form list".
These messages will not result in any updating of cache.  However,
a PK_RESOURCE/PS_CLOSE (disconnect command)  will result in the
same action as the VDISC call, that is, all form jobs will be
removed from the connected form list.
 
When sending a series of messages (multiple VSENDs), use the SND boolean
to increase processing efficiency by letting VSEND buffer messages
until the SND boolean is set TRUE (VB_SEND_NOW).  Setting SND to
FALSE (VB_STILL_MORE) tells VSEND that it can buffer the message if
possible to allow more efficient sending with other subsequent messages.
When the user uses VB_STILL_MORE (FALSE), he or she should take care
to insure that a VB_SEND_NOW (TRUE) VSEND is issued in a timely manner,
otherwise the message may not be sent when expected by the programmer.
 
The message (MSG) variable will normally remain unchanged upon
return from VSEND.  The only change that can happen, is that the
message length (in MSG.FIELD_VALUE) will be adjusted to reflect the
length of the field value already in cache.  If needed the value
will be padded with blanks.  This is done, since the first VSEND,
which resulted in the field value being placed in cache, also determines
the "official" field length that will be use in subsequent sends.
 
 
*ERROR CODES*
 
VI_SUCCESS - (all message but PK_RESOURCE/PS_CLOSE, and
              PK_FIELD_VALUE/PS_PUT)
             The message in MSG was sent to all form jobs
             in the connected form list.  If there were
             a send error to a form job, that form job was
             dropped off the list.  If there were no form
             jobs on the list (no forms connected), the
             message was not sent to anyone.
 
             (PK_RESOURCE/PS_CLOSE)
             The message in MSG was sent to all form jobs
             in the connected form list.  In addition, since
             this is a "disconnect" request, all form jobs
             were removed from the "connected form list".
             This action is the same action as the VDISC
             call.
 
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.
 
*WIZARD*
 
Marginal performance improvments can be made by monitoring from connections,
and skipping the VSEND call when there are no forms connected.
However, even when there are no forms connected, the PK_FIELD_VALUE/PS_PUT
field update messages must still be processed to keep the field value
cache up to date.  Since most of the VSEND calls will be
for processing the PK_FIELD_VALUE/PS_PUT messages, it is recommended
that VSEND be called regardless of whether any forms are connected
to the user's task.
 
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.
 
}