TAA Tools

 RTVUSRSPCE      RETRIEVE USER SPACE ENTRY              TAASPCC

 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.

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.