The Retrieve User Space Entry command is designed to work with i5/OS
provided APIs when you want to process a list in CL. If you are
going to process the list entries in a HLL, you would not use this
command. Instead, you should call QUSRTVUS directly.
A typical command is entered as:
RTVUSRSPCE USRSPC(&SPACEL/&SPACE) ENTLEN(&ENTLEN) +
The command requests the next entry from the user space described.
The STRPOS parameter is a return variable. It is passed in as the
location of the entry you want returned. It is passed back as the
value you entered plus the ENTLEN value. STRPOS must be declared as
*CHAR LEN(4). The intent of updating the value on return is so it is
ready for the next entry to be requested.
The RTNVAR parameter is a return variable. It will contain a data
structure for the entry being processed.
For an example of how to use RTVUSRSPCE, see the companion tool
The command is written so that the processing program will remain
active by default because the normal use occurs in a loop. To end
the processing program, you must specify SETLR(*YES) as a separate
step. To prevent a misuse of the command, the RPG H1 indicator will
be set on if SETLR(*YES) is specified and the program has not been
Command parameters *CMD
USRSPC The qualified name of the user space to be created.
ENTLEN Entry length. This must be declared as *CHAR LEN(4)
and must contain the entry length as a binary value.
If you are using RTVUSRSPCI, this value can be
passed directly from that command.
STRPOS Start position. This is a return variable and must
be declared as *CHAR LEN(4). It is passed in as the
position of the entry you want returned. The value
must be in binary. It is passed back as the entry
you passed in plus the ENTLEN value. The intent is
that you would use this command in a loop and step
thru the list one entry at a time.
If you are using RTVUSRSPCI, the value can be passed
directly from that command.
RTNVAR Return variable. It must be declared as *CHAR
LEN(1000). The variable will normally contain a
structure. The structure will be left adjusted into
the variable. You would probably use the %SUBSTRING
function to extract the field information from the
SETLR This is an *ON/*OFF value that defaults to *OFF. It
controls the setting of LR when the processing
program returns. The *ON value causes a normal
completion where the program is deactivated. The
*OFF setting is used as the default as most uses of
RTVUSRSPCE are often repeated and this allows faster
When the processing program is no longer needed, the
SETLR(*ON) value should be specified or RCLRSC.
When SETLR(*YES) is specified, the program will not
perform the call to QUSRTVUS function. It will end
immediately with LR on and the value of the return
variables will not be changed. To prevent a misuse
of the command, the RPG H1 indicator is used to
denote an error where *YES is specified and the
program has never been active.
Because RTVUSRSPCI has return variables, it can only be executed in a
CL program. The intent of RTVUSRSPCE is to work in conjunction with
None, the tool is ready to use.
Objects used by the tool
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVUSRSPCE *CMD TAASPCC QATTCMD
TAASPCCR *PGM RPG TAASPCCR QATTRPG
Note that there is no CL program. The RPG program is the command