The Retrieve RPG Call Parameters command retrieves the information
about the parameters used for a specific CALL operation in an RPG
source member. The information is passed back in two arrays.
** RTNPRM. Contains the field names used as parameters for a
specific Call operation. There is room for 100 parameters
(the system has a limit that is much smaller). The intended
use is to be processed as an array. Each element is 10 bytes.
The array is built in inverse order (the information about the
first parameter is at element 100).
** RTNVAL. Contains the attributes of the parameter defined in a
data structure. This is intended as an alternate array for
the RTNPRM value. Each element is 10 bytes. See the later
definition of the data structure.
A typical command would be:
DCL &RTNPRM *CHAR LEN(1000)
DCL &RTNVAL *CHAR LEN(1000)
DCL &NBRPRM *DEC LEN(3 0)
.
RTVRPGCALL MBR(xxx) SRCFILE(yyy) PGM(ABC) +
RTNPRM(&RTNPRM) RTNVAL(&RTNVAL) +
NBRPRM(&NBRPRM)
The command is used by the DSPRPGCALL tool.
It is valid to specify *ALL or *FIRSTCALL for a program that does not
have any parameters being passed to it. In this case the NBRPRM
return variable will contain 0.
Escape messages
---------------
Escape messages you may wish to monitor for are:
TAA9883 A required Externally Described file does not exist
on the library list.
TAA9894 The sequence number does not exist or is not the
first record of a statement.
TAA9895 No CALL commands were found.
TAA9896 No CALL command was found for a specific program
name.
TAA9897 The command found at the specified sequence number
is not a CALL command.
Data structure for RTNVAL
-------------------------
1 - 1 Field type
C = Char
P = Packed decimal
B = Binary
S = Zoned decimal
X = Constant
K = Key list
N = *NAMV
2 - 6 Field length
7 - 8 Number of decimals (blank for character types)
9 - 9 Field use (See later discussion)
Blank = Unused (only defined in the program)
U = Used (only used in the program)
X = Changed (some change occurs in the program)
10 - 10 Field code
Bit 0 is on for Externally Described
Bit 1 is on for PLIST Parameter
Bit 3 is on for an Array
Bit 4 is on for a Data Structure
Bit 5 is on for a Data Structure sub field
For a complete understanding of the information in the
data structure, see the RTVRPGFLD tool.
Command parameters *CMD
------------------
MBR The member to be retrieved from. Only RPG source
types are supported.
SRCFILE The qualified file name of the source file. The
file defaults to QRPGSRC. The library value
defaults to *LIBL. *CURLIB may also be used.
CALLNAME The value in Factor 2 to identify the CALL Op code
to be used or the source sequence number where the
CALL exists. Three possible entry types may be
made:
1) The default is *FIRSTCALL which should be used if
you want the first or only CALL in the source.
2) The value of Factor 2 on the CALL statement. The
first value that matches will be used. The string
of data placed in the parameter is used to scan
against Factor 2 of a CALL Operation code.
Therefore if you have a literal as the program name,
specify the literal value. If you have a field name
as the program name, specify the field name. This
value is intended for when there is a unique Call in
the program that is not the first CALL operation.
3) The statement number of the CALL operation. A 6
digit entry must be used with all digits entered and
no decimal point. For example, if the CALL
operation is 150.00 in SEU, specify 015000 as the
statement number. The statement number is intended
for the case where you have multiple calls to the
same program name and you need to be specific. See
also the NXTCALL parameter.
RTNPRM A required return variable that will contain the
field names used as parameters for a specific Call
operation. There is room for 100 parameters (the
system has a limit that is much smaller). The
intended use is to be processed as an array. Each
element is 10 bytes. The array is built in inverse
order (the first parameter is at element 100. The
variable must be specified as *CHAR LEN(1000).
RTNVAL A required return variable that will contain the
corresponding field attributes of the parameters.
This is intended as an alternate array for the
RTNPRM value. Each element is 10 bytes. See the
previous discussion of the data structure that is
returned for each parameter. The variable must be
specified as *CHAR LEN(1000).
NBRPRM An optional return variable that will contain the
number of parameters returned in the RTNPRM value.
If used, it must be specified as *DEC LEN(3 0).
FACTOR2 An optional return variable that will contain the
value of Factor 2 of the Call Operation. The
intended use of this value is to assist in
displaying which Call is being described. If used,
it must be specified as *CHAR LEN(14).
RTNPGM An optional return variable that will contain the
value of the program name on the Call operation if
it can be determined. If a literal is used, the
return program appears without surrounding quotes.
If a field name is used which is a constant, the
program name is attempted to be extracted from the
constant value. If a field name is used that is not
a constant, the program name cannot be determined
and the value will be blank. If used, it must be
specified as *CHAR LEN(10).
RTNPGMLIB An optional return variable that will contain the
value of the program library name on the Call
operation if it can be determined. If a qualified
program name is used as a literal, the return
program library appears without surrounding quotes.
If a field name is used which is a constant, the
program library name is attempted to be extracted
from the constant value. If an unqualified program
name is used as a literal or in a constant, the
return library value will be blank. If a field name
is used that is not a constant, the program library
cannot be determined and the value will be blank.
If used, it must be specified as *CHAR LEN(10).
PGMSTMT An optional return variable that will contain the
sequence number of the statement where the Call
operation was found. If used, it must be specified
as *CHAR LEN(6).
CALLOP An optional return variable that will contain the
Call operation found on the statement. If used, it
must be specified as *CHAR LEN(10).
NXTCALL A *YES/*NO parameter for whether the Call after the
Source Statement number specified in the CALLNAME
parameter should be used. *NO is the default
meaning that the specific Statement number named
contains the Call Operation code to use.
*YES may only be specified when a Statement number
is named for the CALLNAME parameter. If *YES is
specified, the source is read until the statement
number is found and then the search for a Call
begins on the next statement.
The intent of the *YES value is to allow a calling
program to access all of the Call commands and their
parameter lists used in a program. This would be
done by first asking for *FIRSTCALL and then using
the returned value for PGMSTMT as the CALLNAME value
along with NXTCALL(*YES).
RQDEXTDSC Determines whether any externally described files
are required. *YES is the default. If an
Externally Described file is specified in the
source, it must exist on the library list or an
escape message will occur.
*NO may be specified in which case if an Externally
Described file exists, the field specifications are
used. If an Externally Described file does not
exist, no error occurs, but the information about
some of the fields may be missing.
Restrictions
------------
Because the command returns variables, it may only be used in a CL
program.
The tool relies on the RTVRPGFLD tool which has several restrictions.
The *ENTRY parameters may not be defined by a /COPY statement.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR Edit variable
HLRMVMSG HLL Remove message
RPGSTSDS RPG Status DS
RTVRPGFLD Retrieve RPG fields
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVRPGCALL *CMD TAARPGP QATTCMD
TAARPGPC *PGM CLP TAARPGPC QATTCL
TAARPGPR *PGM RPG TAARPGPR QATTRPG
|
