TAA Tools
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 Up to Top