The  Retrieve Cancel  Key  command retrieves  the  action of  the  last
system  display function (including  the command prompter)  and returns
the  setting of the Cancel  (F12) and/or Exit key  (F3).  This allows a
program using  a  system  display  function to  determine  whether  the
system display was  ended with the Enter key versus  the Cancel or Exit
key.  The QUSRJOBI API is used to retrieve the information.

Note  that the  API does not  reflect the  use of  the Cancel/Exit keys
from user display files.  If a  system display is ended with F3 or  F12
followed by  a user  function that  uses a display  file, the  API will
return  the value  from the  last system display.   The  companion tool
CHGCNLKEY may be helpful  when mixing the use  of both system and  user
display  functions.   CHGCNLKEY  will set  the  cancel/exit keys  until
another system display function occurs.

A  typical  use of  the  command  has been  incorporated  into the  TAA
WRKALLSPLF  command.   This  displays one  or  more spooled  files with
several options.   If  Option 5  (DSPSPLF) is  used, the  Enter key  is
used  to  move  to  the  next  spooled  file.    To  end  the  function
immediately,  the tool now uses RTVCNLKEY and  ends if either F3 or F12
was used.

A typical series of commands would be:

             DCL        &EITHERKEY *CHAR LEN(4)
              .
                        /* Some display */
             RTVCNLKEY  EITHERKEY(&EITHERKEY)
             IF         (&EITHERKEY *EQ '*ON') DO /* Cancelled */
             SNDESCMSG  MSG('The xxx function was ended by the +
                          use of the Cancel or Exit key')
             ENDDO      /* Cancelled */

RTVCNLKEY escape messages you can monitor for
---------------------------------------------

None.  Escape messages from based on functions will be re-sent.

RTVCNLKEY Command parameters                          *CMD
----------------------------

   CNLKEY        An optional  return parameter  that will  contain  *ON
                 or *OFF  depending on whether  the Cancel F12  key was
                 used on  the last function.   If specified, the return
                 variable must be specified as *CHAR LEN(4).

   EXITKEY       An optional  return parameter  that will  contain  *ON
                 or  *OFF depending  on  whether the  Exit  F3 key  was
                 used on  the last function.  If  specified, the return
                 variable must be specified as *CHAR LEN(4).

   EITHERKEY     An  optional  return parameter  that will  contain *ON
                 or *OFF  depending  on whether  either the  Cancel  or
                 the  Exit key  was  used  on the  last  function.   If
                 specified,  the return  variable must be  specified as
                 *CHAR LEN(4).


Restrictions
------------

Because the  command returns  a  variable, the  RTVCNLKEY may  only  be
used in a CL program.

Prerequisites
-------------

The following TAA Tools must be on your system:

     SNDESCINF       Send escape information

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVCNLKEY     *CMD                   TAAJOFM       QATTCMD
   TAAJOFMC      *PGM       CLP         TAAJOFMC      QATTCL