USE of the WHEN COMMAND in ASPECT
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                             written by:
                    Ralph Deitrick   CIS 76547,3434
                    Paul Heim        CIS 74066,635



There has been much confusion over the apparent lack of response to the use of
the WHEN command.  This possibly results from the lack of a clear understanding
of how the command is implemented and the precautions that must be observed
during use of the WHEN command.  The Datastorm ASPECT Manual's discussion of
the WHEN command is not adequately clear and precise for many of us.

The following discussion applies to the use of ASPECT's WHEN in both PCPLUS
for DOS Version 2 and PCPLUS for Windows Version 1 except where noted.  The
syntax for the WHEN command in the two Versions of ASPECT is similar but not
totally identical as illustrated below.


     In DOS:         WHEN {index} "prompt" transmit "response"
               or    WHEN {index} "prompt" call procedure
               or    WHEN DISCONNECT call procedure


     In Windows:     WHEN target {index} "prompt" call procedure
               or    WHEN {event} call procedure

               where the various events are as listed on pages 2*230 and 2*231
               of the Windows Aspect Manual.


The WHEN command remains in effect until it is "cleared" or it is redefined by
reissuing the command with a different prompt/event.  Good scripting practice
would dictate that a WHEN command should be cleared at such time that it is no
longer required.  Closing WHEN statements is accomplished as illustrated below.

     In DOS:         CWHEN {index}
               or    CWHEN DISCONNECT

     In Windows:     CLEARWHEN target {index}
               or    CLEARWHEN {event}


In general _ALL_ WHEN commands are implemented to operate in the same manner.
When the prompt/event is encountered, the WHEN command is "marked" for it to
be executed.  HOWEVER, it will _NOT_ be executed _UNTIL_ the present command
in progress is _COMPLETED_ except for the case noted in EXCEPTION below.

The following is a discussion of commands that interfere with the _immediate_
execution of a WHEN command.

     1) WHEN occurring during a WAITFOR -

        The WHEN command will not be acted upon until the WAITFOR prompt is
        satisfied or the "timeout" period of the WAITFOR has been exceeded.
        This means that if you are using a WHEN command to catch a prompt such
        as "Press <CR>" while you WAITFOR another prompt, the WHEN will NOT be
        executed until the WAITFOR has "timed out". (See EXCEPTION below.)  If
        you have specified 'WAITFOR {prompt} FOREVER', the program will be hung
        up and will NEVER execute the WHEN command. This is one reason to be
        extremely careful about using the timeout value of 'FOREVER'.

     2) WHEN occurring during a CALL PROCEDURE -

        This situation is similar to the WAITFOR condition.  Until the program
        _returns_ from the called procedure (no matter how many single commands
        there are in the procedure) the WHEN will not be executed until the
        program returns from the "called" procedure.

     3) Multiple WHEN encounters -

        If a WHEN prompt is encountered several times during the execution of
        another command, the WHEN command will only be executed _ONCE_ upon
        completion of the active command.  The number of times the WHEN has
        been "marked" is not kept in a counter to indicate multiple executions
        at the time it is acted upon.


EXCEPTION:
~~~~~~~~~
As is usually the case, there is an _EXCEPTION_ to the above discussion.  In
the special case of the ASPECT DOS Version 2 WHEN command:

                   WHEN {index} "prompt" transmit "response"

the "response" will be transmitted EVEN during a WAITFOR or similar command.
This is _ONLY_ true when the "transmit" action is specified.




                        SOLUTION to the DILEMMA
                        ~~~~~~~~~~~~~~~~~~~~~~~

Many approaches have been devised to obtain relatively immediate response to
the WHEN command by various script writers.  Some of these "work arounds" are
presented below to give the user some ideas for alternate coding.  The common
"Press <CR>" during a WAITFOR is used as a representative example for which the
usual form (illustrated for PCPLUS for Windows Version 1 ASPECT) that _doesn't_
work is

             WHEN target 0 "Press <CR>" call SendCR
             WAITFOR "Choice !" 60

          proc SendCR
             transmit "^M"
          endproc


Implementation methods:
~~~~~~~~~~~~~~~~~~~~~~

     1) Use of multiple WHEN commands -

        This involves the substitution of another WHEN command in place of the
        WAITFOR until the WAITFOR prompt is reached.

             WHEN target 0 "Press <CR>" call SendCR
             WHEN target 1 "Choice !" call SendChoice
             Flag=1
             while Flag
             endwhile

          proc SendCR
             transmit "^M"
          endproc

          proc SendChoice
             clearwhen target 0
             clearwhen target 1
             transmit "{Choice command}^M"
             Flag=0
          endproc


     2) Cycling short period WAITFOR -

        This method provides the same effect as a default waitfor (30 seconds)
        but the while/endwhile loop will allow time for the when target to
        jump in with it's response while the waitfor is not active during the
        looping process.  (Coding courtesy of Gregg Hommel.)

          when target 0 "to Continue" call SendCR
          tries = 1
          while tries < 31                       ; loop for 30 seconds
             waitfor "target string" 1           ; limit waitfor to 1 second
             if success
                transmit "response"
                exitwhile                        ; break out of while loop
             endif
             tries ++
          endwhile

          proc SendCR
              transmit "^M"
          endproc


     3) More than 3 prompts to catch -

        Since the WHEN commands are limited to three, the following is a means
        of catching multiple prompts (which may exceed three) by using RGETS
        and SWITCH commands.

            proc main
               integer Flag=1

               while Flag
                  RGET Prompt
                  call CheckPrompt
               endwhile
               .                      ; remainder of script
               .
               .
            endproc

            proc CheckPrompt
               switch Prompt
                  case "to Continue"
                     transmit "^M"
                  endcase
                  case "prompt1"
                     transmit "Response1^M"
                  endcase
                  case "prompt2"
                     transmit "Response2^M"
                  endcase
                  case "Final prompt"
                     transmit "Final Response^M"
                     Flag=0
                  endcase
               endswitch
            endproc


     4) WHEN during call procedure -

        In order to keep a WHEN active during a procedure call it is necessary
        to reissue the WHEN command at the beginning of the called procedure.
        The WHEN command then needs to be reimplemented after returning to the
        procedure from which the call was initiated.  This would normally mean
        that the WHEN command should be repeated immediately after the call
        command.

        In the event the procedure call is the result of a when command, it
        will be necessary to provide for a return to a location such that the
        WHEN command is reimplemented in the procedure which issued the call.
        This may mean placing the WHEN statement inside a while/endwhile loop
        such as used in suggestion 1) or may require the judicious use of a
        SETJMP/LONGJMP combination.  Remember that the SETJMP command must be
        located in the script _BEFORE_ the procedure call that results in the
        use of the LONGJMP to return.  It is then necessary to reimplement
        the WHEN command, and define the location in the script to GOTO.



                               CAUTION
                               *******

The discussion contained herein specifically applies to the programs PCPLUS
for DOS Version 2.xx ASPECT and PCPLUS for Windows Version 1.xx ASPECT.  Any
future DOS and/or Windows versions may incorporate changes to the syntax and
behavior of the WHEN command.



                          --- end of file ---