RTVUSRSPCI      RETRIEVE USER SPACE INITIALIZATION     TAASPCB

 The Retrieve  User Space Initialization  command has a  special purpose
 to  work with  the system  provided  APIs in  a CL  program  to provide
 lists (e.g.  lists of members or objects) in user spaces.

 The steps required to use a list are:

   1.   Create  a user space  (See the QUSCRTUS program  or the TAA tool
        CRTUSRSPC).

   2.   Fill the space with a list  by using a CALL to a  system program
        such as QUSLOBJ.

   3.   Retrieve the  initialization information from the  list (See the
        QUSRTVUS   program  or  the   command  provided   by  this  tool
        RTVUSRSPCI).

   4.   Retrieve one entry  at a time  from the list  (See the  QUSRTVUS
        program or the TAA tool RTVUSRSPCE).

   5.   In  some  cases,  the  entry  you  receive  is  only  enough  to
        identify  the  job,  the  object  etc.    that you  really  want
        information on.   In  this  case you  must  do another  call  to
        retrieve the specific information.

 Many functions that want to  use an API list use a CL  program to begin
 processing.  The  first three steps can be done from CL.   Step 4 and 5
 (retrieving  of an  entry and  specific information)  can be  done from
 either CL or a HLL program.   Depending on what is to be done  with the
 information, you can use either either approach.

 For example,  if you are  going to perform  a CL command on  each entry
 of  the list,  it is probably  easier to  perform the  retrieve step in
 CL.  If you are going  to print the information, it is probably  easier
 to use a HLL program.

 Each  of the  API list  functions produces  a standard  heading set  of
 information  in the  user  space.   Following this  information  is the
 list.  The  offset of  where the  list starts  and the  length of  each
 entry may  change on a  future release.   The heading area  contains an
 offset  to where  the list starts  and the  length of  each entry.   To
 protect  your program against future  release changes, this information
 should be accessed  as an initialization  step rather than hard  coding
 the offset and entry length into your program.

 The purpose  of RTVUSRSPCI is to access  the initialization information
 and  return it so it  is ready to be  used in the next  step.  The next
 step can  be  either in  CL  or  the values  may  be passed  to  a  HLL
 program.

 The initialization information you need to process a list is:

   **   The offset (start position) to where the list starts.

   **   The number of entries in the list.

   **   The  length  of each  entry  (Each  entry is  normally  multiple
        fields.    These are  passed as  a  data structure.    The entry
        length is the length of the data structure).

 A typical command is entered as:

         RTVUSRSPCI    USRSPC(QTEMP/SPACE1) STRPOS(&STRPOS) +
                         NBRENT(&NBRENT) ENTLEN(&ENTLEN)

 The last three  parameters are  'return values'  where the  information
 is passed back to your CL program.

 The  RTVUSRSPCI command  calls  the QUSRTVUS  program  with the  proper
 parameters to access the information needed for initialization.

 A few important points:

   **   The STRPOS field  must be declared as *CHAR  LEN(4).  It holds a
        binary  value.  Unlike the  QUSRTVUS program, the value returned
        is not the  offset, but the actual  start position.  You  do not
        need to add 1 to the value to begin processing.

   **   The  NBRENT field  must be  declared as  *DEC LEN(9  0).   It is
        returned  in decimal format to allow  a simple count and compare
        in CL or a HLL to  determine when the end of list has  occurred.

   **   The ENTLEN field must  be declared as *CHAR LEN(4).   It holds a
        binary value which describes the length of each entry.

 CL Example
 ----------

 The following  shows the code necessary to  produce and process a list.
 CL is used for  the entire example.   The example, shows the  structure
 of what needs  to be done for  any list, but the function  performed is
 not very  practical.  A list  of *JOBQ objects in the  QGPL library are
 accessed  and a message is  sent for each one  found.  In this example,
 Step 5 (retrieve specific  information) is not needed because  the list
 entry itself contains all the necessary information.

              PGM
              DCL        &ENTLEN *CHAR LEN(4)
              DCL        &NBRENT *DEC LEN(9 0)
              DCL        &FULLSPACE *CHAR LEN(20)
              DCL        &FULLOBJ *CHAR LEN(20)
              DCL        &OBJ *CHAR LEN(10)
              DCL        &LIB *CHAR LEN(10)
              DCL        &SPACE *CHAR LEN(10)
              DCL        &SPACEL *CHAR LEN(10)
              DCL        &OBJTYPE *CHAR LEN(10)
              DCL        &STRPOS *CHAR LEN(4)
              DCL        &RTNVAR *CHAR LEN(1000)
              DCL        &COUNT *DEC LEN(9 0)
                         /* Create space using TAA command */
              CHGVAR     &SPACE 'SPACE2'
              CHGVAR     &SPACEL 'QTEMP'
              CRTUSRSPC  USRSPC(&SPACEL/&SPACE)
                         /* Next two CHGVARs build up 20 byte     */
                         /*   variables as needed for the CALL    */
                         /*   to QUSLOBJ                          */
              CHGVAR     &FULLSPACE (&SPACE *CAT &SPACEL)
              CHGVAR     &FULLOBJ   ('*ALL      QGPL')
                         /* Call to QUSLOBJ is the API to fill    */
                         /*   the space with an object list. It   */
                         /*   requests the *JOBQ objects in QGPL. */
                         /*   OBJL0100 is the format name of the  */
                         /*   list produced.                      */
              CALL       QUSLOBJ PARM(&FULLSPACE 'OBJL0100' +
                           &FULLOBJ '*JOBQ')
                         /* Retrieve the initialization values    */
                         /*   as described in this tool           */
              RTVUSRSPCI USRSPC(&SPACEL/&SPACE) STRPOS(&STRPOS) +
                           NBRENT(&NBRENT) ENTLEN(&ENTLEN)

 LOOP:                   /* Start processing loop                 */
                         /*   Count and check for total in list   */
              CHGVAR     &COUNT (&COUNT + 1)
              IF         (&COUNT *LE &NBRENT) DO /* Process entry   */
                         /* Retrieve the entry using TAA command    */
                         /*   The &STRPOS value is initially set    */
                         /*     by the RTVUSRSPCI command. On each  */
                         /*     use of RTVUSRSPCE, the next &STRPOS */
                         /*     value is automatically returned.    */
                         /* The ENTLEN is the same for each use  */
              RTVUSRSPCE USRSPC(&SPACEL/&SPACE) ENTLEN(&ENTLEN) +
                           STRPOS(&STRPOS) RTNVAR(&RTNVAR)
                         /* Extract individual fields from RTNVAR */
                         /*   The format of each list differs.    */
                         /*   See the list data section for the   */
                         /*   API that you are using              */
              CHGVAR     &OBJ %SST(&RTNVAR 1 10)
              CHGVAR     &LIB %SST(&RTNVAR 11 10)
              CHGVAR     &OBJTYPE %SST(&RTNVAR 21 10)
                         /* This example only sends a message  */
              SNDPGMMSG  MSG(&OBJ *CAT &LIB *CAT &OBJTYPE)
              GOTO       LOOP
              ENDDO      /* Process entry */
                         /* RTVUSRSPCE defaults to return with LR  */
                         /*   off to allow faster access. When the */
                         /*   loop is complete, use SETLR(*ON) or  */
                         /*   RCLRSC                               */
              RTVUSRSPCE USRSPC(&SPACEL/&SPACE) ENTLEN(&ENTLEN) +
                           STRPOS(&STRPOS) RTNVAR(&RTNVAR) SETLR(*ON)
              ENDPGM

 In this example,  Step 5 was not needed because  the entry retrieved by
 RTVUSRSPCE  contains all the  necessary information to  send a message.
 If this were  not the case, another  call would have  to be done  using
 the information received by RTVUSRSPCE.

 For example,  assume that you  want the  detail information for  all of
 the spooled  files for a specific user.   After RTVUSRSPCE is executed,
 the identifying  information about  one  spooled file  is known.    You
 would  then do  a  call to  QUSRSPLA  to retrieve  the  details of  the
 spooled file (e.g.   page length, the form type).   It is possible that
 the  spooled file  will no  longer exist.   After  the list  of spooled
 files was generated, it  is possible that the spooled file  was printed
 or deleted by the  time the call to QUSRSPLA is done.   You can monitor
 for this condition.

 RPG Example
 -----------

 If  you need  a  HLL program  to process  the  list entries,  the first
 three steps  (Creating the space,  filling the  space with  a list  and
 retrieving  the  initialization  values)  can  still  be  done  in  CL.
 Assume you  have copied all of  the previous CL statements  down to the
 label LOOP.

 Instead of performing  the processing  loop function in  CL, you  would
 call  a HLL  program  with the  information  retrieved from  RTVUSRSPCI
 such as:

              CALL       PGM(RPGPGM) PARM(&FULLSPACE &NBRENT +
                           &ENTLEN &STRPOS)

 The  following is the  complete RPG  program.   It prints one  line per
 entry in the list.

      FQPRINT  O   F     132     OF     PRINTER
      I* DS for the entry length
      IDSLEN       DS
      I                                    B   1   40ENTLN
      I* DS for the start position
      IDSSTR       DS
      I                                    B   1   40STRPS
      I* DS for the makeup of each list entry
      I*   The information is hard coded to assist in understanding.
      I*   The information could have been copied in using PSOBJL0100
      I*     member in QATTRPG. See the LIST DS provided
      I*     in the described member.
      IDSRCV       DS
      I                                        1  10 OBJECT
      I                                       11  20 LIB
      I                                       21  30 OBJTYP
      C           *ENTRY    PLIST                           Parm list
      C                     PARM           USRSPC 20        User space
      C                     PARM           NBRENT  90       Nbr of entrs
      C                     PARM           DSLEN            DS entry len
      C                     PARM           DSSTR            DS str pos
      C* Do for the number of entries passed in
      C                     DO   NBRENT                     Do nbr of
      C                     CALL 'QUSRTVUS'                 Call extract
      C                     PARM           USRSPC           User space
      C                     PARM           STRPS            Start pos
      C                     PARM           ENTLN            Entry length
      C                     PARM           DSRCV            Data struct
      C* Print a line for each entry
      C                     EXCPTPRINT                      Print a line
      C* Bump for next start position
      C                     ADD  ENTLN     STRPS            Bump
      C                     END                             Do nbr of
      C* End of program
      C                     SETON                     LR    Set LR
      C                     RETRN                           Return
      OQPRINT  E  1             PRINT
      O                         OBJECT    10
      O                         LIB       22
      O                         OBJTYP    34

 See  the previous  discussion in the  CL example about  the handling of
 Step 5 and  how it may  be necessary to monitor  for a situation  where
 the  specific  information  cannot  be  received  because  the  job  or
 spooled  file etc.   is no longer in  the system.   In RPG, you monitor
 by specifying an indicator on the  call and then looking in the  status
 area.  You would need to add the following to your program:

      I* DS for exception status conditions
      IEXPSTS     SDS
      I                                       40  46 MSGID
      .
      .
      C                     CALL 'xxxxxxxx'             42  Job info
      .
      .
      C* Check for error on CALL
      C   42                DO                              Call error
      C           MSGID     IFEQ 'xxxxxxx'                  Specific err
      C* Your processing such as ignore the condition
      C                     ELSE                            Other error
      C* Your processing for other errors such as SETON Hx and return
      C                     END                             Other error
      C                     END                             Call error

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

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

    STRPOS        Start  position.  This  is a return  variable and must
                  be declared  as *CHAR  LEN(4).   It will  contain  the
                  offset  plus 1  in  binary.   This  means that  it  is
                  ready  to  use as  the  start  position  of the  first
                  entry in any list.

    NBRENT        Number  of  entries.   This is  a return  variable and
                  must be declared  as *DEC LEN(9  0).  It will  contain
                  the  number  of entries  in  the  list.   It  is  your
                  responsibility  to stop  processing the list  when the
                  total number of entries has been processed.

    ENTLEN        Entry length.  This must  be declared as *CHAR  LEN(4)
                  and will be passed back as a binary value.

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

 Because RTVUSRSPCI has  return variables, it can only be  executed in a
 CL program.

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

 None.

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

 None, the tool is ready to use.

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

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

    RTVUSRSPCI    *CMD                       TAASPCB       QATTCMD
    TAASPCBR      *PGM           RPG         TAASPCBR      QATTRPG

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

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.