The Rotate  List command  allows a  list to  be passed  and returns  an
element  by  rotating  thru  the  list.    When  the  last  element  is
returned,  the next use of ROTLST will  return the first element.  This
can be useful when dealing with  a list of items which must  be wrapped
around.

A  typical  use  of the  command  would  be  to  receive  a list  as  a
parameter.     Assume  you   had  defined  the   following  in  command
definition:

             PARM       KWD(LIST) TYPE(*NAME) LEN(10) MIN(1) MAX(40) +
                          PROMPT('Item name')

If a CL  program is used  as the CPP  (Command Processing Program),  it
could use  the ROTLST command  to keep  returning the next  element and
wrap around when the list is complete.

             PGM        PARM(&LIST)
             DCL        &LIST *CHAR LEN(402)
             DCL        &ELEMENT *CHAR LEN(100)
             DCL        &CURNBR *DEC LEN(5 0)
             DCL        &ITEM *CHAR LEN(10)
 LOOP:       ROTLST     LIST(&LIST) ELMLEN(10) ELEMENT(&ELEMENT) +
                          CURNBR(&CURNBR)
             CHGVAR     &ITEM &ELEMENT

The program  would branch to LOOP each time it  needed the next item in
the list.

The program using  ROTLST should  not change  the value  of the  CURNBR
parameter unless you  want to start again  at the first element  in the
list.   This  is used by  ROTLST to  determine the  next element  to be
processed.   On  the first  use of ROTLST,  the CURNBR  value should be
zero.

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

   LIST          The  list  as  passed  from  command  definition.    A
                 maximum  of 6000 bytes  may be  specified.   Your list
                 length may be less.

   ELMLEN        The  element  length.   The length  cannot  exceed 100
                 bytes.   This would  be the  same  value as  specified
                 for LEN on the command definition.

   ELEMENT       A required  return variable that  must be  declared as
                 *CHAR  LEN(100).   The  value  returned  will be  left
                 adjusted.

   CURNBR        This is  a  required  return  variable  that  must  be
                 declared as *DEC LEN(5 0).

                 On the  first use, the  value passed to  ROTLST should
                 be  zero.   When  ROTLST completes,  the  return value
                 will  be the  number of the  element in  the list that
                 is  returned.    You  should  not  change  this  value
                 during the  program unless you want to  start again at
                 the  first  element  in the  list.    When  the number
                 passed to ROTLST  represents the  last element in  the
                 list, the number  is automatically reset to  cause the
                 first element to be returned.

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

Because  the command returns  parameters, it can  only be used  in a CL
program.

Only simple lists are supported (no use of ELEM keywords).

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

None.

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

None, the tool is ready to use.

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

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

   ROTLST        *CMD                   TAACLQS       QATTCMD
   TAACLQSC      *PGM       CLP         TAACLQSC      QATTCL