The Retrieve User  Space Entry command  is designed to work  with i5/OS
provided  APIs when  you want  to process  a list  in CL.   If  you are
going  to process  the list entries  in a HLL,  you would  not use this
command.  Instead, you should call QUSRTVUS directly.

A typical command is entered as:

             RTVUSRSPCE USRSPC(&SPACEL/&SPACE) ENTLEN(&ENTLEN) +
                          STRPOS(&STRPOS) RTNVAR(&RTNVAR)

The command requests the next entry from the user space described.

The STRPOS parameter  is a  return variable.   It is  passed in as  the
location of  the entry  you want returned.   It is  passed back  as the
value  you entered plus the  ENTLEN value.  STRPOS  must be declared as
*CHAR LEN(4).  The intent of updating  the value on return is so it  is
ready for the next entry to be requested.

The RTNVAR  parameter is  a return  variable.  It  will contain  a data
structure for the entry being processed.

For  an  example of  how  to  use RTVUSRSPCE,  see  the  companion tool
RTVUSRSPCI.

The command  is written  so  that the  processing program  will  remain
active by  default because the  normal use  occurs in a  loop.  To  end
the  processing program,  you must  specify  SETLR(*YES) as  a separate
step.   To prevent a  misuse of the command, the  RPG H1 indicator will
be set  on if SETLR(*YES)  is specified  and the  program has not  been
active.

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

   USRSPC        The qualified  name of the  user space to  be created.

   ENTLEN        Entry  length.  This must be  declared as *CHAR LEN(4)
                 and must contain the entry  length as a binary  value.
                 If  you  are  using  RTVUSRSPCI,  this  value  can  be
                 passed directly from that command.

   STRPOS        Start  position.  This  is a return  variable and must
                 be declared as *CHAR LEN(4).   It is passed in as  the
                 position of  the entry you  want returned.   The value
                 must  be in binary.   It is  passed back as  the entry
                 you  passed in plus  the ENTLEN value.   The intent is
                 that you  would use this  command in  a loop and  step
                 thru the list one entry at a time.

                 If you  are using RTVUSRSPCI, the value  can be passed
                 directly from that command.

   RTNVAR        Return  variable.    It  must  be  declared  as  *CHAR
                 LEN(1000).   The  variable  will  normally  contain  a
                 structure.  The  structure will be left  adjusted into
                 the  variable.  You would  probably use the %SUBSTRING
                 function to  extract the  field information  from  the
                 structure.

   SETLR         This is an *ON/*OFF  value that defaults to *OFF.   It
                 controls  the  setting   of  LR  when  the  processing
                 program  returns.    The  *ON  value  causes  a normal
                 completion  where the  program  is deactivated.    The
                 *OFF setting  is used as  the default as most  uses of
                 RTVUSRSPCE  are often repeated and  this allows faster
                 results.

                 When the processing program  is no longer needed,  the
                 SETLR(*ON) value should be specified or RCLRSC.

                 When SETLR(*YES)  is specified,  the program  will not
                 perform  the call to  QUSRTVUS function.   It will end
                 immediately with LR  on and  the value  of the  return
                 variables will  not be changed.   To prevent  a misuse
                 of  the  command,  the RPG  H1  indicator  is used  to
                 denote  an  error  where  *YES  is  specified  and the
                 program has never been active.

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

Because RTVUSRSPCI has return variables,  it can only be executed  in a
CL program.   The intent of  RTVUSRSPCE is to work  in conjunction with
RTVUSRSPCI.

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

None.

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

None, the tool is ready to use.

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

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

   RTVUSRSPCE    *CMD                       TAASPCC       QATTCMD
   TAASPCCR      *PGM           RPG         TAASPCCR      QATTRPG

Note  that there  is no  CL program.   The RPG  program is  the command
processing program.