The Retrieve Generic Object command provides a simple method of
processing a list of generic objects in a CL program. Each use of
the command returns the basic information about a single object with
the name, library, type, attribute, and text description. The list
may be retained and processed multiple times.
A single object or *ALL objects may be requested for *ALL or a
specific object type.
A typical series of commands would be:
DCL &CURNBR *DEC LEN(7 0)
DCL &RTNOBJ *CHAR LEN(10)
.
LOOP: RTVGENOBJ OBJ(yyy/xxx*) OBJTYPE(*ALL) +
CURNBR(&CURNBR) RTNOBJ(&RTNOBJ)
IF (&CURNBR *GT 0) DO /* Process */
/* */
/* Your processing of &RTNOBJ */
/* */
GOTO LOOP
ENDDO /* Process */
The CURNBR parameter is required. When a 0 is passed, the API
QUSLOBJ is used to create the TAAGENOBJ user space object in QTEMP
with the requested information for object, library, and object type.
The command accesses the user space and returns with information for
the first object. CURNBR is returned with a 1. The next use of
RTVGENOBJ will return the second object. For each object returned,
CURNBR is increased by one to be ready to retrieve the next object.
When the CURNBR value is returned as 0, there are no more objects to
be processed and the TAAGENOBJ user space is deleted by default.
By specifying RETAIN(*YES), the information from the user space may
be processed multiple times. Since 0 is returned for CURNBR when no
more objects match the request, the same user space information is
ready to be processed again.
When the user space is created, the request in terms of object,
library, and object type is stored in the user space. If CURNBR is
passed to the command as 0 and the user space exists, the current
request is compared against the stored request in the user space. If
they are the same, the list is not regenerated.
If a different request is made in terms of object, library, and
object type, the CURNBR value must be 0. You must start processing
at the first object in the list.
An escape message will be sent if CURNBR is greater than 0 and the
TAAGENOBJ *USRSPC object does not exist. Either a new list is being
attempted to be processed or the *USRSPC object has been deleted from
QTEMP.
RTVGENOBJ escape messages you can monitor for
---------------------------------------------
TAA9893 No objects of the generic and type exist.
Escape messages from based on functions will be re-sent.
RTVGENOBJ Command parameters *CMD
----------------------------
OBJ The qualified name or generic name of the object.
The special value *ALL may also be specified. The
library value defaults to *LIBL. A specific
library, *CURLIB, *ALLUSR, *USRLIBL, or *ALL may be
entered.
OBJTYPE The object type. *ALL is the default. Use the
prompter for the list of allowed values.
CURNBR The current number of the generic list of objects to
be accessed. This is a required parameter where the
variable must be declared as *DEC LEN(7 0).
The number should be 0 for the first time RTVGENOBJ
is used for a new object or generic object name.
It the TAAGENOBJ *USRSPC object in QTEMP does not
exist and CURNBR is passed in as 0, the user space
will be created, the return values filled from the
first generic object, and the CURNBR variable is
returned as 1. This allows a simple loop to be
performed where the next use of RTVGENOBJ will
re-access the existing *USRSPC information and
return the next object.
When the current number is passed back as 0, there
are no more objects that meet the criteria and the
*USRSPC is deleted if RETAIN(*NO) is specified.
It is valid to reprocess the same information from
the user space by specifying RETAIN(*YES) after the
CURNBR is returned as 0.
RTNOBJ The return object name. This is an optional
parameter that if specified, must be declared as
*CHAR LEN(10).
RTNLIB The return library name. This is an optional
parameter that if specified must be declared as
*CHAR LEN(10).
RTNTYP The return object type. This is an optional
parameter that if specified must be declared as
*CHAR LEN(7).
RTNATR The return object attribute. This is an optional
parameter that if specified must be declared as
*CHAR LEN(10).
RTNTXT The return text description. This is an optional
parameter that if specified must be declared as
*CHAR LEN(50).
TOTOBJ The total number of objects that match the criteria.
This is an optional parameter that if specified must
be declared as *DEC LEN(7 0).
RETAIN A *YES/*NO parameter for whether to retain the
TAAGENOBJ *USRSPC object in QTEMP if no more objects
exist (the CURNBR return value will be 0).
*NO is the default to cause the user space object to
be deleted when no more objects exist to be
returned.
*YES may be specified to allow the user space object
to be retained so the same information may be
processed again.
Restrictions
------------
Because the RTVGENOBJ command returns variables, RTVGENOBJ may only
be used in a CL program.
A limit of 150,000 objects that match a generic request may exist.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHGUSRSPC Change user space
CRTUSRSPC Create user space
RTVUSRSPC Retrieve user space
SNDESCINF Send escape information
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVGENOBJ *CMD TAAOBLL QATTCMD
TAAOBLLC *PGM CLP TAAOBLLC QATTCL
|
