The Retrieve Command Parameters command retrieves an array of
information where each element contains a data structure of the
parameter attributes. The command is intended for use in programs
where the attributes of the command parameters are needed.
The source member is accessed to retrieve the information. The
keyword form of the source must be used. Not all parameter
attributes are supported.
A typical series of commands would be:
DCL &RTNVAL *CHAR LEN(9900)
DCL &ELEM *CHAR LEN(220)
DCL &PARM *CHAR LEN(10)
.
RTVCMDPARM MBR(xxx) SRCFILE(yyy) +
RTNVAL(&RTNVAL) RTNCDE(&GOOD)
/* Extract the first element */
CHGVAR &ELEM %SST(&RTNVAL 1 220)
/* Extract the parameter name */
CHGVAR &PARM %SST(&ELEM 1 10)
When processing in an HLL, an externally described data structure may
be used. The name is TAACMDXP and the field names all begin with PM.
See the later example.
When processing in CL, the data structure layout is:
Name Type Length Str pos Parameter name
---- ---- ------ ------- --------------
PMKWD *CHAR 10 1 KWD
PMTYPE *CHAR 10 11 TYPE
PMLEN *CHAR 5 21 LEN
PMDECP *CHAR 2 26 LEN dec positions
PMRTNV *CHAR 4 28 RTNVAL
PMCONS *CHAR 30 32 CONSTANT
PMDFT *CHAR 15 62 DFT (1st 15 bytes)
PMRSTD *CHAR 4 77 RSTD
PMMIN *CHAR 5 81 MIN
PMMAX *CHAR 5 86 MAX
PMALWU *CHAR 4 91 ALWUNPRT
PMALWV *CHAR 4 95 ALWVAR
PMFULL *CHAR 4 99 FULL
PMEXPR *CHAR 4 103 EXPR
PMCHOC *CHAR 30 107 CHOICE
PMPROM *CHAR 30 137 PROMPT
PMPGM *CHAR 4 167 PGM
PMDTAA *CHAR 4 171 DTAARA
PMFILE *CHAR 4 175 FILE
PMKEYP *CHAR 4 179 KEYPARM
PMQLEL *CHAR 1 183 Qual or Elem
PMELEN *CHAR 5 184 Elem length
PMVARY *CHAR 4 188 Vary option
PMVAR2 *CHAR 5 192 Vary *INT2/*INT4
Reserved 23 197
The PMQLEL field is blank for a normal parameter, Q=QUAL type, and
E=ELEM type.
The PMELEN field is blank for a normal parameter. It contains the
sum of the ELEM statements lengths as will be passed to the CPP
without the 2 byte binary field.
The PMDFT field will contain the first 15 bytes of the value if it is
specified on the KWD statement (not on the QUAL or ELEM statements).
There is room for 45 elements in the array. This may exceed the
maximum number of parameters that are valid on a command.
Source files up to a length of 240 bytes may be processed.
MAX GT 1
--------
When the MAX is greater than 1, a 2 byte binary field appears at
position 1 of the parameter which describes the number of parameters
passed.
QUAL and ELEM keyword use
-------------------------
QUAL statements are handled by adding up the lengths from multiple
statements so that the KWD parameter has the length that will be
passed to the CPP.
ELEM statements are handled by adding up the lengths from multiple
statements plus 2 so that the the KWD parameter has the length that
will be passed to the CPP.
If QUAL and ELEM statements describe TYPE(*DEC) values, the length
that is added is the packed length not the digit length as this is
how the data is passed to the CPP.
If MAX is greater than 1, an additional 2 bytes are added to the
length to account for the additional binary count.
Escape messages
---------------
TAA9892 The command does not have any parameters or none
were found.
Calling the CPP directly
------------------------
The CPP (TAACMDXR) may be called directly. The following would be
typical RPG code.
E ARR 45220 Return array
I* Externally described data structure of each element
IPARMS E DSTAACMDXP
.
C *ENTRY PLIST Parm list
C PARM ARR Array
C PARM RTNCDE 8 Return code
Note that an override may be necessary to describe the source file
and member to be processed before calling the CPP. The file name
used in the CPP is QCMDSRC.
The RTNCDE will contain:
** FOUND. All keywords have been properly found.
** NONE. No parameters found (see previous TAA9892 message).
Command parameters *CMD
------------------
MBR The source member name. It must be a CMD type.
SRCFILE The qualified source file name of the source file.
QCMDSRC is the default in *LIBL. *CURLIB may also
be used as a library qualifier.
RTNVAL The return value with the array of information. It
must be specified as *CHAR LEN(9900). There is room
for 45 elements of 220 bytes each. Each element is
a data structure. See the previous discussion on
the data structure.
NBRPARM An optional return value which will contain the
number of parameters specified on the command. If
specified, it must be declared as *DEC LEN(3 0).
Parsing technique
------------------
The source statement may represent multiple source records based on
the continuation characters.
A restriction exists that the keyword form of each parameter must be
used. The source is scanned for values such as 'TYPE('. If the
value exists in a comment before the normal keyword such as in a
comment, incorrect data will be returned. If the prompter is used,
it would be very rare if an error would occur.
The QUAL and ELEM statements are found by scanning for a colon. The
ELEM statement is identified by a search for ' ELEM '.
Restrictions
------------
** The source member must contain keywords. Positional notation
is not supported.
** A maximum of 45 keywords may be returned. Positional notation
is not supported.
** Valid command source must be used.
** Because the command returns parameters, it can only be used in
a CL program.
** If QUAL and ELEM statements are used, they must occur in the
order of use such as they must follow the KWD statement. In
addition, if an ELEM statement uses a Qualified name for the
TYPE parameter, the QUAL statement must follow the ELEM
statement (it cannot precede it).
** See detail restrictions in the discussion of the Parsing
Technique.
Prerequisites
-------------
The following TAA Tools must be on your system:
HLRMVMSG HLL Remove message
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVCMDPARM *CMD TAACMDX QATTCMD
TAACMDXC *PGM CLP TAACMDXC QATTCL
TAACMDXR *PGM RPG TAACMDXR QATTRPG
TAACMDXP *FILE PF TAACMDXP QATTDDS
|
