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
|
