The Retrieve CLP Call Parameters command retrieves the attributes of
the parameters passed to a CL or CLLE program. The source member
must be specified.
A typical command would be:
DCL &RTNVAR *CHAR LEN(1100)
DCL &RTNVAL *CHAR LEN(5000)
DCL &NBRPRM *DEC LEN(3 0)
.
RTVCLPCALL MBR(xxx) SRCFILE(yyy) PGM(*FIRSTCALL) +
RTNVAR(&RTNVAR) RTNVAL(&RTNVAL) +
NBRPRM(&NBRPRM)
The RTNVAR parameter is an array of 100 11 byte elements where each
element is a variable name or the value *CONSTANT (if a constant is
passed).
The RTNVAL parameter is an array of 100 50 byte elements where each
element is a data structure which contains the attributes of the
parameter and the first 34 bytes if a constant is passed.
Both arrays are loaded from the back meaning the first parameter is
placed in the last element to allow faster lookup operations.
Although the system restricts the number of parameters that can be
passed on a CALL to less than 100, the array size allows for growth.
Both CALL and CALLPRC are supported.
The NBRPRM parameter is the number of parameters that exist. This
can be helpful in determining where to start a lookup operation. If
no parameters are passed on the CALL, this value will be 0.
The PGM parameter defaults to *FIRSTCALL meaning the first CALL or
CALLPRC statement found in the program. You may also specify:
** A specific name. The program or variable name should be
specified.
** A statement number where the CALL or CALLPRC is to be found.
Escape messages
---------------
Escape messages you may wish to monitor for are:
TAA9891 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.
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.
Command parameters *CMD
------------------
MBR The source member to be read to search for the CALL
command.
SRCFILE The qualified file name of the source file. The
file name defaults to QCLSRC. The library value
defaults to *LIBL. *CURLIB may also be used.
Source files up to 240 bytes in length may be read.
PGM The program name on the CALL statement 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 (or CALLPRC) command
in the source.
2) The name of a program on the CALL statement. The
first program by the specified name will be used.
Any library qualifier is ignored. If the program is
a variable name, specify a leading & for the program
name. This value is intended for when there is a
unique Call in the program that is not the first
CALL statement.
3) The statement number of the CALL statement. A 6
digit entry must be used with all digits entered and
no decimal point. For example, if the CALL
statement 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. If a
Call command has continuation source records, the
statement number of the first record must be used.
See also the NXTCALL parameter.
RTNVAR A required return variable that will contain an
array of the attributes of the parameters that are
passed on the Call. The return variable must be
declared as type *CHAR LEN(1100). Each element is
11 bytes long. The array is loaded from the back
with the first element found placed in positions
1090 - 1100. Unused positions will be blank.
If a variable is used as a parameter, the name will
be proceeded by a &.
If a constant is used, the value will be *CONSTANT.
The alternating array with the attributes of each
parameter is returned in the RTNVAL parameter.
RTNVAL A required return variable that will contain an
array of the attributes of the parameters that are
passed on the call. The return variable must be
declared as type *CHAR LEN(5000). Each element is
50 bytes long and represents a data structure. See
the later definition. The array is loaded from the
back with the first element found placed in
positions 4951 - 5000. Unused positions will be
blank.
NBRPRM An optional return variable that will contain the
number of parameters being passed on the CALL. If
specified, the variable must be declared as *DEC
LEN(3 0).
PGMNAM An optional return variable that will contain the
the first 14 bytes of the Call (or CALLPRC). This
helps identify the Call statement. This value may
be helpful if a specific program name is not used on
the PGM statement. If a variable is used as the
program name, the variable name including the & will
be returned. If specified, the variable must be
declared as *CHAR LEN(14).
RTNPGM An optional return variable that will contain the
the name of the program being called if it can be
determined. If a variable is used as the program
name, the name of the program cannot be determined
and the value will be blank. If the program name is
specified in quotes, the quotes will be removed. If
specified, the variable must be declared as *CHAR
LEN(10).
RTNPGMLIB An optional return variable that will contain the
the name of the library of the program being called
if it can be determined. If a variable is used as
the library name, the name of the program cannot be
determined and the value will be blank. If the
library name is specified in quotes, the quotes will
be removed. If specified, the variable must be
declared as *CHAR LEN(10).
PGMSTMT An optional return variable that will contain the
sequence number of the first record where the Call
command was found. This value may be helpful if a
specific statement number was not used on the PGM
statement. If specified, the variable must be
declared as *CHAR LEN(6). See also the NXTCALL
parameter.
RTNPGMVAR An optional return variable that will contain the
name of the variable used for the program if a
variable is used. If specified, the variable must
be declared as *CHAR LEN(11).
RTNLIBVAR An optional return variable that will contain the
name of the variable used for the library if a
variable is used. If specified, the variable must
be declared as *CHAR LEN(11).
CALLCMD An optional return variable that will contain the
the name of the Call command (CALL or CALLPRC) that
is used. If specified, the variable must be
declared as *CHAR LEN(10).
NXTCALL A *YES/*NO parameter for whether the Call after the
Source Statement number specified in the PGM
parameter should be used. *NO is the default
meaning that the specific Statement number named is
the CALL statement to use.
*YES may only be specified when a Statement number
is named for the PGM 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 PGM 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.
RTNVAL Data Structure
---------------------
Each 50 byte element is made up as follows:
Type 1 - 5 *CHAR or *DEC
Length 6 - 10
Decimals 11 - 12
Value 14 - 46 Value (up to 34 bytes)
Reserved 47 - 50 Reserved
All values are returned in *CHAR form.
If a value is passed surrounded by apostrophes, the apostrophes will
appear in the Value, but the length will be the actual length of the
data.
If a plus or minus is passed proceeding a decimal value, the length
will not include the plus or minus.
Restrictions
------------
Because the command returns variables, it can only be used in a CL
program.
Valid syntax of a Call command must be used.
The source member must be a CL or CLLE type.
The TAA RTVCLPVAR command is used to determine the attributes of the
variables. This command has restrictions.
A constant cannot exceed 256 bytes.
It is not expected that the technique used to access the information
is a 100% match with the technique used by the system.
A maximum of 100 parameters is supported.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR Edit variable
HLRMVMSG HLL Remove message
RTVCLPVAR Retrieve CLP variables
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVCLPCALL *CMD TAACLQJ QATTCMD
TAACLQJC *PGM CLP TAACLQJC QATTCL
TAACLQJC2 *PGM CLP TAACLQJC2 QATTCL
TAACLQJR *PGM RPG TAACLQJR QATTRPG
|
