The STRKEY  command provides  a prompt  that allows the  user to  enter
the starting key value for a file.

The  intent of  this command  is that  the  program which  invokes this
command  would use the OVRDBF command  POSITION parameter and then call
a HLL program or do a RCVF command.

This  would  allow  a  'set  lower  limit'  function  from  within  CL.
Because CL  does not  allow you to  close the file  and reopen  it, you
can only use the function once per CL program.

STRKEY would display a prompt which appears is as follows:

**********************************************************************
*                                                                    *
*  Start at key value for  File ORDER        Library PRODUCTION      *
*                                                                    *
*   Value            Field       Length  Dec  Text                   *
*   _______________  ORDNBR           5    0  Order number           *
*   _______________  LINITM           3    0  Line item number       *
*                                                                    *
*                                                                    *
*   Partial values can be specified for any character key.           *
*   Low order keys can be left blank.                                *
*   *BLANK may be specified for a character field.                   *
*                                                                    *
*   F3=Exit  F6=Use first key in file  F9=Enter lower case  F12=Can  *
*                                                                    *
**********************************************************************

                 The  F9 key acts  as a Flip/Flop  key between entering
                 in upper and lower case.

Performance implications
------------------------

To put up the prompt requires that DSPFFD and DSPFD be executed against
the specified file to determine  the key fields and their descriptions.
These are slow running functions  and  therefore  STRKEY should only be
used for problem determination or other seldom used functions.

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

   FILE          The qualified file  name of  the file  to be  prompted
                 for  the keys.    This must  be a  keyed  file with  a
                 single format.

   FMT           The  return variable  with the name  of the  format of
                 the file.  This must be a 10 byte character field.

   HEX           The return  variable with  the hex  value of  the  key
                 requested.    This  must  be   a  256  byte  character
                 variable.

   KEYCNT        The  number of  keys that  the  user specified  on the
                 prompt.  This must be a 3 byte character field.

   RTNCDE        The  return code  for the  command processing program.
                 It must be  defined as an  8 byte character field  and
                 will have the following values:

                       GOOD         Normal return
                       MULTFMTS     The file has more than one format
                       CF3          F3 (Exit) was requested
                       CF6          F6 Use first key in the file
                                       was requested

   DSPFFD        A *YES/*NO  value that  defaults to *YES.   This  is a
                 performance   option  to   determine  if   DSPFFD  has
                 already been used.

Example
-------

The following  is an  example of  a CL  Program which  uses the  STRKEY
function.   In  this  case a  file TESTKEY  is  to be  read  in the  CL
Program  beginning  at  a user  specified  key  location.   The  STRKEY
command is  used to  prompt the  user for  where to  start reading  the
file and  an  OVRDBF command  is used  to position  the file.   The  CL
Program  is written  without knowledge of  how many  keys exist  in the
file,  the type of fields (e.g.  packed)  which make up the key nor how
many the user  has specified.  The  OVRDBF command is executed  through
a  call to  QCMDEXC with  the POSITION  parameter specifying  the start
location.

             PGM
             DCLF       TESTKEY
             DCL        &FILE *CHAR LEN(10)
             DCL        &FMT *CHAR LEN(10)
             DCL        &HEX *CHAR LEN(256)
             DCL        &KEYCNT *CHAR LEN(3)
             DCL        &CMD *CHAR LEN(500)
             DCL        &RTNCDE *CHAR LEN(8)
             STRKEY     FILE(TESTKEY) FMT(&FMT) HEX(&HEX) +
                          KEYCNT(&KEYCNT) RTNCDE(&RTNCDE) DSPFFD(*NO)
             IF         (&RTNCDE *NE 'GOOD    ') GOTO BADRTN
             CHGVAR     &CMD ('OVRDBF FILE(TESTKEY) ' *CAT +
                          'POSITION(*KEYAE ' *CAT &KEYCNT *BCAT +
                          &FMT *BCAT 'X' *CAT '''' *CAT +
                          &HEX *TCAT '''' *CAT ')')
             CALL       QCMDEXC PARM(&CMD 500)
             RCVF
              .         /* Normal processing of record */
              .
             RETURN     /* Good return */
BADRTN:      SNDPGMMSG  MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Bad +
                          return code of ' *CAT &RTNCDE *TCAT +
                          ' from STRKEY pgm') MSGTYPE(*ESCAPE)
             ENDPGM

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

None

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

The following TAA Tools must be on your system:

      CVTHEX     Convert a value to hex

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

None, the tool is ready to use.

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

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

   STRKEY        *CMD                      TAADBFI        QATTCMD
   TAADBFID      *FILE         DSPF        TAADBFID       QATTDDS
   TAADBFIC      *PGM          CLP         TAADBFIC       QATTCL
   TAADBFIR      *PGM          RPG         TAADBFIR       QATTRPG