RTVOBJLST       RETRIEVE OBJECT LIST                   TAAOBJV

 The Retrieve Object List  command provides a large return  variable for
 a  list of objects.   The  command is  designed to replace  the DSPOBJD
 outfile  if  minimal information  per object  is required.   An  API is
 used to  retrieve the  information  to provide  for better  performance
 than the  DSPOBJD outfile.   100 bytes  of information is  returned for
 up  to 90  objects.   If more  than 90 objects  satisfy the  request, a
 second retrieve is needed.

 A single object, generic  objects, or all  objects may be returned  for
 a specific object  type or for all  types.  A generic  library name may
 also be used.

 A  return  variable of  9000  bytes is  used.   Each  object  takes 100
 bytes.  The layout is as follows:

            1 - 10   Object name
           11 - 20   Library name
           21 - 27   Object type
           28 - 28   Information status (see later section)
           29 - 38   Object attribute
           39 - 48   User attribute
           49 - 98   Text
           99 - 100  Reserved

 If you have only a few  objects being returned and you need  additional
 information, consider  RTVOBJD.   If you  have a lot  of objects  being
 returned  and need  additional  information,  you are  better  off with
 DSPOBJD OUTFILE parameter or the API interface.

 If  less  than 90  objects  are returned,  the  remaining space  in the
 large return variable will be blank.

 If no  objects exist  for the  request, TAA9893  is sent  as an  escape
 message.

 The TAAOBJLST  user space is created  in QTEMP to process  the request.
 The  QUSLOBJ API (Format 0200) is used  to write the object information
 into  the  user  space.    The  RTVOBJLST  command  processing  program
 retrieves  the  information  from  the   list  and  builds  the  return
 variable.

 Processing less than 90 objects
 -------------------------------

 If you  know that less than 90 objects  will be returned, the following
 would be typical coding to  retrieve the objects in  a loop.  The  code
 is in a format that  is ready to be copied to a CL  program.  First use
 CPYTAA  TAAARCMBR(RTVOBJLST)  to  copy  this  documentation  source  to
 QATTINFO in TAATOOL.

              DCL        &OBJINF *CHAR LEN(9000)
              DCL        &WORK *CHAR LEN(100)
              DCL        &OBJ *CHAR LEN(10)
              DCL        &LIB *CHAR LEN(10)
              DCL        &OBJTYP *CHAR LEN(7)
              DCL        &OX *DEC LEN(5 0)
               .
                         /********************************************/
                         /*                                          */
  RTV:                   /*       Retrieve object list               */
                         /*                                          */
                         /********************************************/
              RTVOBJLST  OBJ(xxx) OBJTYPE(*ALL) OBJINF(&OBJINF)
              CHGVAR     &OX -99
                         /********************************************/
                         /*                                          */
  LOOP:                  /*       Loop thru OBJINF return value      */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OX (&OX + 100)
              CHGVAR     &WORK %SST(&OBJINF &OX 100)
              IF         (&WORK *NE ' ') DO /* Some object */
                         /********************************************/
                         /*                                          */
                         /*       Extract individual object info     */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OBJ %SST(&WORK 1 10)
              CHGVAR     &LIB %SST(&WORK 11 10)
              CHGVAR     &OBJTYP %SST(&WORK 21 7)
              CHGVAR     &INFSTS %SST(&WORK 28 1)
              CHGVAR     &OBJATR %SST(&WORK 29 10)
              CHGVAR     &USRATR %SST(&WORK 39 10)
              CHGVAR     &TEXT %SST(&WORK 49 50)

                         /********************************************/
                         /*                                          */
                         /*       If object no longer exists, bypass */
                         /*                                          */
                         /********************************************/
              CHKOBJ     OBJ(&LIB/&OBJ) OBJTYPE(&OBJTYP)
              MONMSG     MSGID(CPF9801) EXEC(DO) /* Not found */
              GOTO       LOOP
              ENDDO      /* Not found */
                         /********************************************/
                         /*                                          */
                         /*       Your processing of the object      */
                         /*                                          */
                         /********************************************/
              GOTO       LOOP
              ENDDO      /* Some object */

 Processing more than 90 objects
 -------------------------------

 If  more than 90  objects will or  may be returned,  you must loop back
 after each block  of 90 has  been processed.   The special value  *NEXT
 is used for  the object name when the data is  already available in the
 user  space.   The following  would be typical  coding to  retrieve the
 objects in  a loop.   The  code is  in a  format that  is  ready to  be
 copied  to a  CL program.    First use  CPYTAA TAAARCMBR(RTVOBJLST)  to
 copy this documentation source to QATTINFO in TAATOOL.

              DCL        &OBJNAM *CHAR LEN(10)
              DCL        &OX *DEC LEN(5 0)
              DCL        &TOTCNT *DEC LEN(7 0)
              DCL        &OBJINF *CHAR LEN(9000)
              DCL        &OBJCNT *DEC LEN(7 0)
              DCL        &OBJAVL *DEC LEN(7 0)
              DCL        &WORK *CHAR LEN(100)
              DCL        &TOTCNT *DEC LEN(7 0)
              DCL        &OBJ *CHAR LEN(10)
              DCL        &LIB *CHAR LEN(10)
              DCL        &OBJTYP *CHAR LEN(7)
              DCL        &INFSTS *CHAR LEN(1)
              DCL        &OBJATR *CHAR LEN(10)
              DCL        &USRATR *CHAR LEN(10)
              DCL        &TEXT *CHAR LEN(50)
               .
                         /********************************************/
                         /*                                          */
                         /*       Initialize for RTVOBJLST           */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OBJNAM 'xxx'
              CHGVAR     &TOTCNT 0

                         /********************************************/
                         /*                                          */
  RTV:                   /*       Retrieve object list               */
                         /*         Use a variable for object name   */
                         /*           and change as previous         */
                         /*                                          */
                         /********************************************/
              RTVOBJLST  OBJ(xxx/&OBJNAM) OBJTYPE(*yyy) +
                           OBJINF(&OBJINF) OBJCNT(&OBJCNT) +
                           OBJAVL(&OBJAVL)
              CHGVAR     &OX -99
                         /********************************************/
                         /*                                          */
  LOOP:                  /*       Loop thru OBJINF return value      */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OX (&OX + 100)
              CHGVAR     &WORK %SST(&OBJINF &OX 100)
              CHGVAR     &TOTCNT (&TOTCNT + 1)
                         /********************************************/
                         /*                                          */
                         /*       Extract individual object info     */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OBJ %SST(&WORK 1 10)
              CHGVAR     &LIB %SST(&WORK 11 10)
              CHGVAR     &OBJTYP %SST(&WORK 21 7)
              CHGVAR     &INFSTS %SST(&WORK 28 1)
              CHGVAR     &OBJATR %SST(&WORK 29 10)
              CHGVAR     &USRATR %SST(&WORK 39 10)
              CHGVAR     &TEXT %SST(&WORK 49 50)
                         /********************************************/
                         /*                                          */
                         /*       If object no longer exists, bypass */
                         /*                                          */
                         /********************************************/
              CHKOBJ     OBJ(&LIB/&OBJ) OBJTYPE(&OBJTYP)
              MONMSG     MSGID(CPF9801) EXEC(DO) /* Not found */
              GOTO       CHKTOTCNT
              ENDDO      /* Not found */
                         /********************************************/
                         /*                                          */
                         /*       Your processing of the object      */
                         /*                                          */
                         /********************************************/
                .
                .
                         /********************************************/
                         /*                                          */
  CHKTOTCNT:             /*       If Total has been processed, end   */
                         /*                                          */

                         /********************************************/
              IF         (&TOTCNT *EQ &OBJAVL) DO /* All processed */
              GOTO       ENDPCS
              ENDDO      /* All processed */
                         /********************************************/
                         /*                                          */
                         /*       Loop back if less than 8901        */
                         /*                                          */
                         /********************************************/
              IF         (&OX *LT 8901) DO /* LT return area */
              GOTO       LOOP
              ENDDO      /* LT return area */
                         /********************************************/
                         /*                                          */
                         /*       End of block, request next block   */
                         /*                                          */
                         /********************************************/
              CHGVAR     &OBJNAM '*NEXT'
              GOTO       RTV
                         /********************************************/
                         /*                                          */
  ENDPCS:                /*       All objects have been processed    */
                         /*                                          */
                         /********************************************/

 Security considerations
 -----------------------

 You  must   have  some  authority  to  the   objects  to  retrieve  the
 information.  If not, the information  status is set to 'A' and  blanks
 are returned  for the  object attribute,  the user  attribute, and  the
 text.

 Information status
 ------------------

 The one  byte information status  field is taken from  the QUSLOBJ API.
 The codes returned are:

       Blank    The information is returned.
         A      No information returned.  Authority error.
         D      The information is returned, but damage exists.
         L      No information returned.  The object is locked.
         P      The information is returned, but partial damage exists.

 If  the object is exclusively locked,  the information returned for the
 Object attribute, User attribute and Text will be blank.

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

    OBJ           The qualified name  of the object.   A single  object,
                  a  generic object, or  the special  value *ALL  may be
                  used.

                  The  special value  *NEXT may  be used when  more than
                  90 objects exist.  See the previous discussion.

                  The  library  value  defaults  to  *LIBL.     *CURLIB,
                  *USRLIBL,  *ALL,  or  *ALLUSR may  be  specified.    A
                  generic library name may be entered.

    OBJTYPE       See the  command prompt for the  list of object types.
                  The special value  *ALL exists for  all object  types.

    ASPDEV        Specifies  the  auxiliary storage  pool  (ASP)  device
                  name  where  storage for  the  library containing  the
                  object  is allocated.   If  the library  resides in an
                  ASP that  is not  part  of the  thread's library  name
                  space,  this parameter  must  be  specified to  ensure
                  the  correct library is  searched.   If this parameter
                  is used when the  library qualifier specified for  the
                  Object prompt  (OBJ parameter)  is *CURLIB,  *LIBL, or
                  *USRLIBL, ASPDEV(*) is the only valid value.

                  This  parameter  can be  specified  as a  list  of two
                  values  (elements)  or  as   a  single  value.     The
                  possible single values are:

                  * = The ASPs  that are currently part of  the thread's
                  library  name space  will  be searched  to  locate the
                  library.   This includes  the system ASP  (ASP 1), all
                  defined  basic user  ASPs  (ASPs  2-32), and,  if  the
                  thread  has an  ASP group,  the primary  and secondary
                  ASPs in the thread's ASP group.

                  *ALLAVL  = All available ASPs will  be searched.  This
                  includes the  system ASP  (ASP 1),  all defined  basic
                  user ASPs (ASPs  2-32), and all available  primary and
                  secondary  ASPs,   (ASPs  33-255)  with  a  status  of
                  'Available'.

                  *CURASPGRP =  If  the thread  has  an ASP  group,  the
                  primary and secondary  ASPs in the thread's  ASP group
                  will be  searched to locate  the library.   The system
                  ASP  (ASP 1) and  defined basic user  ASPs (ASPs 2-32)
                  will not be searched.   If no ASP group  is associated
                  with the thread, an error will be issued.

                  *SYSBAS  = The  system  ASP (ASP  1)  and all  defined
                  basic  user  ASPs  (ASPs  2-32)  will  be  searched to
                  locate the  library.   No  primary or  secondary  ASPs
                  will  be  searched  even  if the  thread  has  an  ASP
                  group.

                  Element 1: Device

                  The  device name  of the primary  or secondary  ASP to
                  be searched.  The primary  or secondary ASP must  have
                  been  activated (by  varying on  the  ASP device)  and
                  have  a status of  'Available'.   The system  ASP (ASP
                  1)  and defined user  basic ASPs (ASPs  2-32) will not
                  be searched.

                  Element 2: Search type

                  *ASP  =  Specifies  that  only  the  single  auxiliary
                  storage  pool (ASP) device  named in  element 1  is to
                  be searched.

                  *ASPGRP  =  Specifies  that the  entire  group  of the
                  primary auxiliary storage pool  (ASP) device named  in
                  element 1 is to be searched.

    OBJINF        The  return  variable  which  will  contain  100  byte
                  elements  for  up to  90  objects.   If  less  that 90
                  objects are  returned,  the remaining  space  will  be
                  blank.

                  This is an  optional parameter.   If used, it  must be
                  specified as *CHAR LEN(9000).

                  See  the previous  discussion for  the layout  of each
                  element.

    OBJCNT        The  number  of  objects  that  are  returned  in  the
                  OBJINFO  return  variable.    If  less  than   90  are
                  available, the  value will be  the same as  the OBJAVL
                  value.   If more than 90  are available, the first use
                  of the command  will return  90.   Subsequent uses  of
                  the command  will return  either 90  or the  remaining
                  number.

                  This  is an optional parameter.   If used,  it must be
                  specified as *DEC LEN(7 0).

    OBJAVL        The total  number of  available  objects that  can  be
                  returned.  If  less than 90 objects exist,  OBJCNT and
                  OBJAVL  will have  the same  value.   If more  than 90
                  objects  exist,  the  OBJAVL count  will  be  the same
                  value on both  the initial use  of RTVOBJLST and  when
                  OBJ(*NEXT) is used.

                  This is  an optional parameter.   If used, it  must be
                  specified as *DEC LEN(7 0).

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

 Because  the command  returns variables, it  may only  be used  in a CL
 program.

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

 The following TAA Tools must be on your system:

      CRTUSRSPC       Create user space
      SNDESCMSG       Send escape message

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

 None, the tool is ready to use.

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

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

    RTVOBJLST     *CMD                   TAAOBJV       QATTCMD
    TAAOBJVC      *PGM       CLP         TAAOBJVC      QATTCL

Added to TAA Productivity Tools October 1, 1997


Home Page

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