The Retrieve  Next ID command is  designed to return  the next ID  in a
sequence.  For  example, if the last ID input is  ABC, the next ID that
would  be returned is  ABD.  This  allows the assigning  of names based
on the  last ID  that  was used.   This  could be  used  for object  or
member names or  for field names in  a data base file.   Numbers in the
ID are optional.

For a sequential number function, see the tool NBRCTR.

A typical series of commands would be:

             DCL        &LASTID  *CHAR LEN(10)
             DCL        &NEXTID  *CHAR LEN(10)
              .
             RTVNXTID   LASTID(&LASTID) NEXTID(&NEXTID) ALWNBRS(*YES)

Rules
-----

  **   The  input value  must  be 10  characters or  less.   The return
       value will be the same length as the input value.

  **   The first character  of the input  value must be  an upper  case
       A-Z.

  **   The  remaining  characters  must  be  upper  case  A-Z  or  0-9.
       Allowing  numbers   requires  the  use  of  ALWNBRS(*YES).    If
       ALWNBRS(*NO) is  specified,  an  input value  such  as  AB1C  is
       invalid.

  **   The function works  like an odometer.   If the input  value ends
       with  a Z  such as  ABCZ,  the next  ID returned  would  be ABDA
       using  ALWNBRS(*NO).    Note  that  like  an  odometer,  when an
       overflow occurs, the  last position is  set to the lowest  value
       (A)   and  the  preceding   position  is   bumped  one.     With
       ALWNBRS(*YES), the return value would be ABC0.

  **   The  first position of the return value  will never be a number.
       If an  input value  such as  Z9 is  entered,  an escape  message
       will occur  because the first position  cannot be a number.   An
       escape message occurs any time no more IDs can be assigned.

Examples
--------

                  Allow nbrs       No numbers
       Last ID      Next ID         Next ID
       -------    ----------       ----------

        A            B               B
        AAAA         AAAB            AAAB
        AAAZ         AAA0            AABA
        AZZZZZZZZZ   AZZZZZZZ0       BAAAAAAAA
        AZZZZZZZZ9   BAAAAAAAA                    Invalid
        AAA1         AAA2                         Invalid
        AAA9         AABA                         Invalid
        ZZ           Z0                           Invalid
        Z                                         Invalid
        Z9                                        Invalid

RTVNXTID escape messages you can monitor for
--------------------------------------------

      CPF9898    Input value is invalid

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

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

   LASTID        The last  ID that was used.   It must be 10 characters
                 or less.   The first  position must be  an upper  case
                 A-Z.  The  remaining positions must be upper  case A-Z
                 or  if   ALWNBRS(*YES)  is  specified,  the  remaining
                 positions may be 0-9.

                 See the previous rules and examples.

   NEXTID        The  next  ID in  the sequence.    This is  a required
                 return  variable  that  must  be  specified  as  *CHAR
                 LEN(10).

   ALWNBRS       A  *YES/*NO  parameter  for  whether numbers  0-9  are
                 allowed  in  the  LASTID  input  value  or  the NEXTID
                 return value.

                 *NO is the default which  allows only upper case  A-Z.

                 *YES may be  specified to allow numbers  0-9 after the
                 first  character  in  both  the  input  value and  the
                 return value.

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

See the previous rules and examples.

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

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

The following TAA Tools must be on your system:

     SCNVARRGT       Scan variable right
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message

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

None, the tool is ready to use.

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

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

   RTVNXTID      *CMD                   TAANAMB       QATTCMD
   TAANAMBC      *PGM       CLP         TAANAMBC      QATTCL