231 lines
14 KiB
HTML
231 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html
|
||
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html lang="en-us" xml:lang="en-us">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<meta name="security" content="public" />
|
||
<meta name="Robots" content="index,follow" />
|
||
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
<meta name="DC.Type" content="task" />
|
||
<meta name="DC.Title" content="Pass parameters" />
|
||
<meta name="abstract" content="When you pass control to another program or procedure, you can also pass information to it for modification or use within the receiving program or procedure." />
|
||
<meta name="description" content="When you pass control to another program or procedure, you can also pass information to it for modification or use within the receiving program or procedure." />
|
||
<meta name="DC.subject" content="parameter, passing between programs, order of" />
|
||
<meta name="keywords" content="parameter, passing between programs, order of" />
|
||
<meta name="DC.Relation" scheme="URI" content="cflow.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="ucall.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="comer.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="callc.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="callp.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="../cl/callprc.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="../cl/call.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="../apis/CEEDOD.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="../books/sc415606.pdf" />
|
||
<meta name="DC.Relation" scheme="URI" content="tfr.htm" />
|
||
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
<meta name="DC.Format" content="XHTML" />
|
||
<meta name="DC.Identifier" content="passp" />
|
||
<meta name="DC.Language" content="en-us" />
|
||
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
<!-- US Government Users Restricted Rights -->
|
||
<!-- Use, duplication or disclosure restricted by -->
|
||
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
<title>Pass parameters</title>
|
||
</head>
|
||
<body id="passp"><a name="passp"><!-- --></a>
|
||
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
<h1 class="topictitle1">Pass parameters</h1>
|
||
<div><p>When you pass control to another program or procedure, you can
|
||
also pass information to it for modification or use within the receiving program
|
||
or procedure. </p>
|
||
<div class="section"> <p> You can specify the information to be passed on the PARM parameter
|
||
on the <span class="cmdname">Call (CALL)</span> command or the <span class="cmdname">Call Bound Procedure
|
||
(CALLPRC)</span> command. The characteristics and requirements for these
|
||
commands are slightly different.</p>
|
||
<p>For instance, if PROGA contains the
|
||
following command: </p>
|
||
<pre>CALL PROGB PARM(&AREA)</pre>
|
||
<p>then it calls PROGB and passes the value of &AREA to it.
|
||
PROGB must start with the PGM command, which also must specify the parameter
|
||
it is to receive:</p>
|
||
<pre>PGM PARM(&AREA) /* PROGB */</pre>
|
||
<p>For the <span class="cmdname">Call (CALL)</span> command or the <span class="cmdname">Call
|
||
Bound Procedure (CALLPRC)</span> command, you must specify the parameters
|
||
passed on the PARM parameter, and you must specify them on the PARM parameter
|
||
of the PGM command in the receiving program or procedure. Because parameters
|
||
are passed by position, not name, the position of the value passed in the <span class="cmdname">Call
|
||
(CALL)</span> command or the <span class="cmdname">Call Bound Procedure (CALLPRC)</span> command
|
||
must be the same as its position on the receiving PGM command. For example,
|
||
if PROGA contains the following command:</p>
|
||
<pre>CALL PROGB PARM(&A &B &C ABC)</pre>
|
||
<p>it passes three variables and a character string, and if PROGB
|
||
starts with:</p>
|
||
<pre>PGM PARM(&C &B &A &D) /*PROGB*/</pre>
|
||
<p>then the value of &A in PROGA is used for &C in PROGB,
|
||
and so on; &D in PROGB is <samp class="codeph">ABC</samp>. The order of the DCL
|
||
statements in PROGB is unimportant. Only the order in which the parameters
|
||
are specified on the PGM statement determines what variables are passed.</p>
|
||
<p>In
|
||
addition to the position of the parameters, you must pay careful attention
|
||
to their length and type. Parameters listed in the receiving procedure or
|
||
program must be declared as the same length and type as they are in the calling
|
||
procedure or program. Decimal constants are always passed with a length of <samp class="codeph">(15 5)</samp>.</p>
|
||
<p>When
|
||
you use the <span class="cmdname">Call Bound Procedure (CALLPRC)</span> command and
|
||
pass character string constants, you must specify the exact number of bytes,
|
||
and pass exactly that number. The called procedure can use the information
|
||
in the operational descriptor to determine the exact number of bytes passed.
|
||
You can use the API CEEDOD to access the operational descriptor. </p>
|
||
<p>When
|
||
you use the CALL command, character string constants of 32 bytes or less are
|
||
always passed with a length of 32 bytes. If the string is longer than 32,
|
||
you must specify the exact number of bytes, and pass exactly that number.</p>
|
||
<p>The
|
||
following is an example of a procedure or program that receives the value &VAR1:
|
||
</p>
|
||
<pre>PGM PARM(&VAR1) /*PGMA*/
|
||
DCL VAR1 *CHAR LEN(36)
|
||
.
|
||
.
|
||
.
|
||
ENDPGM</pre>
|
||
<p>The CALL command or <span class="cmdname">Call Bound Procedure (CALLPRC)</span> command
|
||
must specify 36 characters: </p>
|
||
<pre>CALLPRC PGMA(ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJ)</pre>
|
||
<p>The following example specifies the default lengths: </p>
|
||
<pre>PGM PARM(&P1 &P2)
|
||
DCL VAR(&P1) TYPE(*CHAR) LEN(32)
|
||
DCL VAR(&P2) TYPE(*DEC) LEN(15 5)
|
||
IF (&P1 *EQ DATA) THEN(CALL MYPROG &P2)
|
||
ENDPGM</pre>
|
||
<p>To call this program, you could specify: </p>
|
||
<pre>CALL PROG (DATA 136)</pre>
|
||
<p>The character string DATA is passed to &P1; the decimal
|
||
value 136 is passed to &P2</p>
|
||
<p>Referring to locally defined variables
|
||
incurs less overhead than referring to passed variables. Therefore, if the
|
||
called procedure or program frequently refers to passed variables, performance
|
||
can be improved by copying the passed values into a local variable and referring
|
||
to the locally defined value rather than the passed value.</p>
|
||
<p>When calling
|
||
an OPM CL program, the number of parameters that are passed to it must exactly
|
||
match the number that is expected by the program. The number that is expected
|
||
is determined at the time the program is created. (The operating system prevents
|
||
you from calling a program with more or fewer parameters than the program
|
||
expects). When calling an ILE program or procedure, the operating system does
|
||
not check the number of parameters that are passed on the call. In addition,
|
||
the space where the operating system stores the parameters is not reinitialized
|
||
between procedure calls. Calling a procedure that expects "n" parameters with
|
||
"n-1" parameters makes the system use whatever is in the parameter space to
|
||
access the "nth" parameter. The results of this action are very unpredictable.
|
||
This also applies to procedures written in other ILE languages that call CL
|
||
procedures or are called by CL procedures.</p>
|
||
<p>This also gives you more
|
||
flexibility when you write ILE CL procedures, because you can write procedures
|
||
that have variable length parameter lists. For example, based on the value
|
||
of one parameter, a parameter that is specified later in the list may not
|
||
be required. If the controlling parameter indicated an unspecified optional
|
||
parameter, the called procedure should not attempt to refer to the optional
|
||
parameter.</p>
|
||
<p>You can also specify the special value *OMIT for any parameter
|
||
that you want to omit from the parameter list. If you specify *OMIT for a
|
||
parameter, the calling procedure passes a null pointer. The procedure that
|
||
is called has to be prepared to handle a null pointer if it refers to a parameter
|
||
that is omitted. In control language (CL), you can check for a null pointer
|
||
by monitoring for MCH3601 on the first reference to the omittable parameter.
|
||
The procedure must take appropriate action if it receives a MCH3601.</p>
|
||
<p>When
|
||
calling procedures, you can pass arguments by reference and by value.</p>
|
||
<p>The
|
||
following example has two CL procedures. The first procedure expects one parameter;
|
||
if that parameter remains unspecified, results will be unpredictable. The
|
||
first procedure calls another procedure, PROC1. PROC1 expects one or two parameters.
|
||
If the value of the first parameter is '1', it expects the second parameter
|
||
as specified. If the value of the second parameter is '0', it assumes that
|
||
the second parameter remained unspecified and used a default value instead.
|
||
PROC1 also uses the CEEDOD API to determine the actual length that is passed
|
||
for the second parameter.</p>
|
||
<div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm">Code license and disclaimer information</a> for
|
||
important legal information.</div>
|
||
<div class="fignone"><pre>MAIN: PGM PARM(&TEXT)/* &TEXT must be specified. Results will be +
|
||
unpredictable if it is omitted.*/
|
||
DCL VAR(&TEXT) TYPE(*CHAR) LEN(10)
|
||
CALLPRC PRC(PROC1) PARM('0')
|
||
CALLPRC PRC(PROC1) PARM('1' &TEXT)
|
||
CALLPRC PRC(PROC1) PARM('1' 'Goodbye')
|
||
ENDPGM
|
||
|
||
PROC1: PGM PARM(&P1 &P2) /* PROC1 - Procedure with optional +
|
||
parameter &P2 */
|
||
DCL VAR(&P1) TYPE(*LGL) /*Flag which indicates +
|
||
whether or not &P2 will be specified. If +
|
||
value is '1', then &P2 is specified */
|
||
DCL VAR(&P2) TYPE(*CHAR) LEN(10)
|
||
DCL VAR(&MSG) TYPE(*CHAR) LEN(10)
|
||
DCL VAR(&PARMPOS) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter position for CEEDOD*/
|
||
DCL VAR(&PARMDESC) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter description for CEEDOD*/
|
||
DCL VAR(&PARMTYPE) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter datatype from CEEDOD*/
|
||
DCL VAR(&PARMINFO1) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter information from CEEDOD */
|
||
DCL VAR(&PARMINFO2) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter information from CEEDOD */
|
||
DCL VAR(&PARMLEN) TYPE(*CHAR) LEN(4) /* +
|
||
Parameter length from CEEDOD*/
|
||
DCL VAR(&PARMLEND) TYPE(*DEC) LEN(3 0) /* +
|
||
Decimal form of parameter length*/
|
||
IF COND(&P1) THEN(DO) /* Parm 2 is+
|
||
specified, so use the parm value for the +
|
||
message text*/
|
||
CHGVAR VAR(%BIN(&PARMPOS 1 4)) VALUE(2) /* Tell +
|
||
CEEDOD that we want the operational +
|
||
descriptor for the second parameter*/
|
||
CALLPRC PRC(CEEDOD) PARM(&PARMPOS &PARMDESC +
|
||
&PARMTYPE &PARMINFO1 &PARMINFO2 &PARMLEN) +
|
||
/* Call CEEDOD to get the length of data +
|
||
specified for &P2*/
|
||
CHGVAR VAR(&PARMLEND) VALUE(%BIN(&PARMLEN 1 4)) /* +
|
||
Convert the length returned by CEEDOD to +
|
||
decimal format*/
|
||
CHGVAR VAR(&MSG) VALUE(%SST(&P2 1 &PARMLEND)) /* +
|
||
Copy the data passed in to a local variable*/
|
||
ENDO
|
||
ELSE CMD(CHGVAR VAR(%MSG) VALUE('Hello')) /* Use +
|
||
"Hello" for the message text*/
|
||
SNDPGMMSG MSG(&MSG)
|
||
ENDPGM
|
||
</pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div>
|
||
<ul class="ullinks">
|
||
<li class="ulchildlink"><strong><a href="ucall.htm">CALL command</a></strong><br />
|
||
When the CALL command is issued by a CL procedure, each parameter value passed to the called program can be a character string constant, a numeric constant, a logical constant, or a CL variable.</li>
|
||
<li class="ulchildlink"><strong><a href="comer.htm">Common errors when calling programs and procedures</a></strong><br />
|
||
This describes the errors encountered most frequently in passing values on a CALL command or a CALLPRC command. Some of these errors can be very difficult to debug, and some have serious consequences for program functions.</li>
|
||
</ul>
|
||
|
||
<div class="familylinks">
|
||
<div class="parentlink"><strong>Parent topic:</strong> <a href="cflow.htm" title="You can use the Call Program (CALL), Call Bound Procedure (CALLPRC), and Return (RETURN) commands to pass control back and forth between programs and procedures.">Control flow and communicate between programs and procedures</a></div>
|
||
</div>
|
||
<div class="reltasks"><strong>Related tasks</strong><br />
|
||
<div><a href="callc.htm" title="The Call Program (CALL) command calls a program named on the command, and passes control to it.">Use the CALL command</a></div>
|
||
<div><a href="callp.htm" title="The Call Bound Procedure (CALLPRC) command calls a procedure named on the command, and passes control to it.">Use the CALLPRC command</a></div>
|
||
<div><a href="tfr.htm" title="This is an example of transferring control to improve performance.">Example: Use the Transfer Control (TFRCTL) command</a></div>
|
||
</div>
|
||
<div class="relinfo"><strong>Related information</strong><br />
|
||
<div><a href="../cl/callprc.htm">Call Bound Procedure (CALLPRC) command</a></div>
|
||
<div><a href="../cl/call.htm">Call (CALL) command</a></div>
|
||
<div><a href="../apis/CEEDOD.htm">Retrieve Operational Descriptor Information (CEEDOD) API</a></div>
|
||
<div><a href="../books/sc415606.pdf" target="_blank">ILE Concepts PDF</a></div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |