Procedure Vcon(nam: ch6; det: ch10; var stat: VI_status_type);
   EXTERNAL;
{*USER*
 
Request a connection to the job specified in NAM.  The info in DET
will be put in the RESOURCE_DETAIL field of the connect request.
 
The job named in NAM will be added to our "connected" job list, so that
its messages will be recognized by this program.  However, the
"connection" is not considered complete until the "connection granted"
message (PK_RESOURCE/PS_GRANT) is received.  Upon receipt of this
message, we know that all current field values "owned" by the job named
in NAM have been sent to us.
 
The processing status will be returned in STAT.
 
If the returned status is VI_CONNECTED, the job named in NAM has been
added to the connected job list.  The caller must still monitor the
connection process to determine that the connection is "complete".
Normally, this is the receipt of a PK_RESOURCE/PS_GRANT message from
the job.  Receipt of this message indicates that the connected job
has sent us all field values and that we are not "in synch".
Prior to this point, the values in cache may not be all up to date.
 
The caller should determine what is a reasonable time to wait for
the connection to be "complete".  If after that time, the connection
is not "complete", a disconnect should be done using VDISC.
The following is an example of code that does a "connect" request
and detects "complete" or "timeout" of the connection process.
 
.lit
 
( MSG_FLAG is flag that will set if a mesasge
  packet is received, TIMER_FLAG is used for
  timeout - both flags must be in same group
  since we use a STLO for the stop, TIMEOUT,
  COMPLETE and ERR are booleans that reflect
  the outcome of the connection process.
  Note that we check for directive errors
  using DIRERR on "critical" directives
  whose failure would hang the program. )
timeout:= false;
complete:= false;
err:= false;
( clean out any old messages from MILSRV, reset
  message receipt flag )
repeat
  sassign(job,'MILSRV');
  rcvmsg(job,recv_msg,stat);
  until stat < 0;
clef(msg_flag);
( request connection )
Vcon('MILSRV','HI THERE  ',vstat);
if vstat = VI_connected
  then begin
    ( connect request sent okay, process responses
      until connect "complete" or "timeout" where
      timeout is 30 seconds without receiving a
      response from requested job )
    mrkt(timer_flag,30,seconds);
    err:= direrr('MRKT1',$dsw);
    repeat
      ( reset message receipt flag prior to receive
        message attempt )
      clef(msg_flag);
      ( receive messages only from MILSRV )
      sassign(job,'MILSRV');
      rcvmsg(job,recv_msg,stat);
      if stat >= 0
        then begin
          ( message received, process, and if not
            complete (PS_GRANT), reset timer )
          process_msg(complete);
          if not(complete)
            then begin
              ( we must cancel previous marktime is
                still running )
              cnmt(timer_flag);
              mrkt(timer_flag,30,seconds);
              err:= direrr('MRKT2',$dsw);
              end;
          end
        else begin
          ( no message from MILSRV, check TIMER_FLAG,
            and if set, declare "timeout", otherwise stop
            and wait for new messages to arrive )
          if rdef(timer_flag) then timeout:= true;
          err:= direrr('RDEF1',$dsw);
          if not(err or timeout) then stlo([msg_flag,time_flag]);
          end;
      until (complete) or (timeout) or (err);
    end
  else begin
    ( VCON failed - task not known to system, or no
      more room in connected job list )
    writeln('VCON ERROR');
    err:= true;
    end;
( since we could have received messages from other tasks
  during this time, we set MSG_FLAG to insure that we
  check for other messages before stopping )
stse(msg_flag);
 
.eli
 
The preceding example is a "full function" restart.  The only feature
it does not have is the ability to handle messages from other tasks
during the connection process.  You can see that you could add
this functionality if needed, by blending this code into your regular
message handling routines.
 
A simpler and less robust
connection process could be done by simply doing the VCON call and
setting a "connection valid" boolean false.  Later, when the
connection is completed (PS_GRANT received), the "connection valid"
would be set, indicating that the connection is "complete" and the
field values can be used.  In many cases, this would be acceptable
as the connections may be simple and made only at program startup
or program reconfiguration.
 
*ERROR CODES*
 
VI_CONNECTED - The connect request was sent to the specified
               job, and that job was added to the connected
               job list.
 
VI_NOT_CONNECTED - The connect request could not be sent
                   becuase there was no room left in the
                   connected job list.
 
VI_CONNECT_LOST - The connect request could not be sent due
                  because job name specified was not known to
                  the system, or other message send error.
 
*WIZARD*
 
The job name specified in NAM is added to the connected job list
prior to the connection being "complete" (PS_GRANT received).  This
is done since we must accept field value messages prior
to receipt of the PS_GRANT message and adjust cache if needed to
reflect those values.
 
Normally, if a connection is denied, the PS_CLOSE message will be sent
to us, and the job will be removed from the connected job list.
However, it is important the the caller understand that this may not
always occur, and must be prepared to handle cases where the
connection is not "complete".
 
}