210 lines
13 KiB
HTML
210 lines
13 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="CALL command" />
|
||
|
|
<meta name="abstract" content="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." />
|
||
|
|
<meta name="description" content="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." />
|
||
|
|
<meta name="DC.subject" content="CALL (Call Program) command, using, Call Program (CALL) command, command, CL, CALL (Call Program), Call Program (CALL), program, calling, use, calling program, using the CALL command, parameter, passing, receiving, example" />
|
||
|
|
<meta name="keywords" content="CALL (Call Program) command, using, Call Program (CALL) command, command, CL, CALL (Call Program), Call Program (CALL), program, calling, use, calling program, using the CALL command, parameter, passing, receiving, example" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="passp.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="lprvl.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="callc.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../cl/call.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../clfinder/finder.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="ucall" />
|
||
|
|
<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>CALL command</title>
|
||
|
|
</head>
|
||
|
|
<body id="ucall"><a name="ucall"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">CALL command</h1>
|
||
|
|
<div><p>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. </p>
|
||
|
|
<div class="section"> <p>A maximum of 255 parameters can be passed to the called program.
|
||
|
|
The values of the parameters are passed in the order in which they appear
|
||
|
|
on the CALL command, and this must match the order in which they appear in
|
||
|
|
the parameter list of the called program. The names of the variables passed
|
||
|
|
do not have to be the same as the names on the receiving parameter list.
|
||
|
|
The names of the variables receiving the values in the called program must
|
||
|
|
be declared to the called program, but the order of the declare commands is
|
||
|
|
not important.</p>
|
||
|
|
<p>No association exists between the storage in the called
|
||
|
|
program and the variables it receives. Instead, when the calling program passes
|
||
|
|
a variable, the storage for the variable is in the program in which it was
|
||
|
|
originally declared. The system passes variables by address. When passing
|
||
|
|
a constant, the calling program makes a copy of the constant, and passes the
|
||
|
|
address of that copy to the called program.</p>
|
||
|
|
<p>The result is that when
|
||
|
|
a variable is passed, the called program can change the value of the variable,
|
||
|
|
and the change is reflected in the calling program. The new value does not
|
||
|
|
have to be returned to the calling program for later use; it is already there.
|
||
|
|
Thus no special coding is needed for a variable that is to be returned to
|
||
|
|
the calling program. When a constant is passed, and its value is changed by
|
||
|
|
the called program, the changed value is not known to the calling program.
|
||
|
|
Therefore, if the calling program calls the same program again, it reinitializes
|
||
|
|
the values of constants, but not of variables.</p>
|
||
|
|
<p>An exception to the previous
|
||
|
|
description is when the CALL command calls an ILE C program. When using the
|
||
|
|
CALL command to call an ILE C program and pass character or logical constants,
|
||
|
|
the system adds a null character (x'00') after the last non-blank character.
|
||
|
|
If the constant is a character string that is enclosed in apostrophes or a
|
||
|
|
hexadecimal constant, the null character is added after the last character
|
||
|
|
that was specified. This preserves the trailing blanks (x '40' characters).
|
||
|
|
Numeric values are not null-terminated.</p>
|
||
|
|
<p>If a CL program might be called
|
||
|
|
using a CALL command that has not been compiled (an interactive CALL command
|
||
|
|
or through the SBMJOB command), the decimal parameters (*DEC) should be declared
|
||
|
|
with <samp class="codeph">LEN(15 5)</samp>, and the character parameters (*CHAR) should
|
||
|
|
be declared <samp class="codeph">LEN(32)</samp> or less in the receiving program.</p>
|
||
|
|
<p>A
|
||
|
|
CALL command that is not in a CL procedure or program cannot pass variables
|
||
|
|
as arguments. Be careful when specifying the CALL command as a command parameter
|
||
|
|
that is defined as TYPE(*CMDSTR). This converts the contents of
|
||
|
|
any variables that are specified on the PARM parameter to constants. The command
|
||
|
|
(CMD) parameters on the <span class="cmdname">Submit Job (SBMJOB)</span> command, <span class="cmdname">Add
|
||
|
|
Job Schedule Entry (ADDJOBSCDE)</span> command, or <span class="cmdname">Change Job
|
||
|
|
Schedule Entry (CHGJOBSCDE)</span> command are examples.</p>
|
||
|
|
<p>Parameters
|
||
|
|
can be passed and received as follows: </p>
|
||
|
|
<ul><li>Character string constants of 32 bytes or less are <em>always</em> passed
|
||
|
|
with a length of 32 bytes (padded on the right with blanks). If a character
|
||
|
|
constant is longer than 32 bytes, the entire length of the constant is passed.
|
||
|
|
If the parameter is defined to contain more than 32 bytes, the CALL command
|
||
|
|
must pass a constant containing exactly that number of bytes. Constants longer
|
||
|
|
than 32 characters are <strong><em>not</em></strong> padded to the length expected by
|
||
|
|
the receiving program. <p>The receiving program can receive less than the
|
||
|
|
number of bytes passed. For example, if a program specifies that 4 characters
|
||
|
|
are to be received and <samp class="codeph">ABCDEF</samp> is passed (padded with blanks
|
||
|
|
in 26 positions), only <samp class="codeph">ABCD</samp> are accepted and used by the
|
||
|
|
program.</p>
|
||
|
|
<p>If the receiving program receives more than the number of bytes
|
||
|
|
passed, the results may be unexpected. Numeric values passed as characters
|
||
|
|
must be enclosed in apostrophes.</p>
|
||
|
|
</li>
|
||
|
|
<li>Decimal constants are passed in packed form and with a length of <samp class="codeph">LEN(15
|
||
|
|
5)</samp>, where the value is 15 digits long, of which 5 digits are decimal
|
||
|
|
positions. Thus, if a parameter of <samp class="codeph">12345</samp> is passed, the
|
||
|
|
receiving program must declare the decimal field with a length of <samp class="codeph">LEN(15
|
||
|
|
5)</samp>; the parameter is received as <samp class="codeph">12345.00000</samp>. <div class="p">If
|
||
|
|
you need to pass a numeric constant to a program and the program is expecting
|
||
|
|
a value with a length and precision other than 15 5, the constant can be coded
|
||
|
|
in hexadecimal format. The following CALL command shows how to pass the value
|
||
|
|
25.5 to a program variable that is declared as LEN(5 2): <pre>CALL PGMA PARM(X'02550F')</pre>
|
||
|
|
</div>
|
||
|
|
</li>
|
||
|
|
<li>Logical constants are passed with a length of 32 bytes. The logical value
|
||
|
|
0 or 1 is in the first byte, and the remaining bytes are blank. If a value
|
||
|
|
other than 0 or 1 is passed to a program that expects a logical value, the
|
||
|
|
results may be unexpected.</li>
|
||
|
|
<li>A floating point literal or floating point special value (*NAN, *INF,
|
||
|
|
or *NEGINF) is passed as a double precision value, which occupies 8 bytes.
|
||
|
|
Although a CL program cannot process floating point numbers, it can receive
|
||
|
|
a floating point value into a character variable and pass that variable to
|
||
|
|
an HLL program that can process floating point values.</li>
|
||
|
|
<li>The system can pass a variable if the call is made from a CL procedure
|
||
|
|
or program. In this case the receiving program should declare the field to
|
||
|
|
match the variable that is defined in the calling CL procedure or program.
|
||
|
|
For example, assume that a CL procedure or program defines a decimal variable
|
||
|
|
that is named &CHKNUM as <samp class="codeph">LEN(5 0)</samp>. Then the receiving
|
||
|
|
program should declare the field as packed with 5 digits total, with no decimal
|
||
|
|
positions. When running a CALL command in batch mode by using the SBMJOB command
|
||
|
|
in a CL procedure or program, the system treats any variables that are passed
|
||
|
|
as arguments like constants.</li>
|
||
|
|
<li>If either a decimal constant or a program variable can be passed to the
|
||
|
|
called program, the parameter should be defined as <samp class="codeph">LEN(15 5)</samp>,
|
||
|
|
and any calling program must adhere to that definition. If the type, number,
|
||
|
|
order, and length of the parameters do not match between the calling and receiving
|
||
|
|
programs (other than the length exception noted previously for character constants),
|
||
|
|
results cannot be predicted.</li>
|
||
|
|
<li>In order for an integer constant to be passed to an integer variable,
|
||
|
|
the constant must be specified in hexadecimal format. The size of the hexadecimal
|
||
|
|
constant and integer variable must be the same.</li>
|
||
|
|
<li>The value *N cannot be used to specify a null value because a null value
|
||
|
|
cannot be passed to another program.</li>
|
||
|
|
</ul>
|
||
|
|
<p>In the following example, program A passes six parameters: one logical
|
||
|
|
constant, three variables, one character constant, and one numeric constant.</p>
|
||
|
|
<pre>PGM /* PROGRAM A */
|
||
|
|
DCL VAR(&B) TYPE(*CHAR)
|
||
|
|
DCL VAR(&C) TYPE(*DEC) LEN(15 5) VALUE(13.529)
|
||
|
|
DCL VAR(&D) TYPE(*CHAR) VALUE('1234.56')
|
||
|
|
CHGVAR VAR(&B) VALUE(ABCDEF)
|
||
|
|
CALL PGM(B) PARM('1' &B &C &D XYZ 2) /* Note blanks between parms */
|
||
|
|
.
|
||
|
|
.
|
||
|
|
.
|
||
|
|
ENDPGM</pre>
|
||
|
|
<pre>PGM PARM(&A &B &C &W &V &U) /* PROGRAM B */
|
||
|
|
DCL VAR(&A) TYPE(*LGL)
|
||
|
|
DCL VAR(&B) TYPE(*CHAR) LEN(4)
|
||
|
|
DCL VAR(&C) TYPE(*DEC)
|
||
|
|
/* Default length (15 5) matches DCL LEN in program A */
|
||
|
|
DCL VAR(&W) TYPE(*CHAR)
|
||
|
|
DCL VAR(&V) TYPE(*CHAR)
|
||
|
|
DCL VAR(&U) TYPE(*DEC)
|
||
|
|
.
|
||
|
|
.
|
||
|
|
. ENDPGM </pre>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> If the fifth parameter passed to PGMB was <samp class="codeph">456</samp> instead
|
||
|
|
of <samp class="codeph">XYZ</samp> and was intended as alphanumeric data, the value would
|
||
|
|
have been specified as <samp class="codeph">'456'</samp> in the parameter.</div>
|
||
|
|
<p>The
|
||
|
|
logical constant '1' does not have to be declared in the calling program.
|
||
|
|
It is declared as type logical and named &A in program B.</p>
|
||
|
|
<p>Because
|
||
|
|
no length is specified on the DCL command for &B, the default length,
|
||
|
|
which is 32 characters, is passed. Only 6 characters of &B are specified
|
||
|
|
(<samp class="codeph">ABCDEF</samp>). Because &B is declared with only 4 characters
|
||
|
|
in program B, only those 4 characters are received. If they are changed in
|
||
|
|
program B, those 4 positions for &B will also be changed in program A
|
||
|
|
for the remainder of this call.</p>
|
||
|
|
<p>The length (LEN) parameter must be specified
|
||
|
|
for &C in program A. If it were not specified, the length would default
|
||
|
|
to the specified value's length, which would be incompatible with the default
|
||
|
|
length expected in program B. &C has a value of <samp class="codeph">13.52900</samp>.</p>
|
||
|
|
<p>&W
|
||
|
|
in program B (&D in program A) is received as a character because it is
|
||
|
|
declared as a character. Apostrophes are not necessary to indicate a string
|
||
|
|
if TYPE is *CHAR. In program A, the length defaults to the value's length
|
||
|
|
of 7 (the decimal point is considered a position in a character string).
|
||
|
|
Program B expects a length of 32. The first 7 characters are passed, but
|
||
|
|
the contents past the position 7 cannot be predicted.</p>
|
||
|
|
<p>The variable &V
|
||
|
|
is a character string <samp class="codeph">XYZ</samp>, padded with blanks on the right.
|
||
|
|
The variable &U is numeric data, <samp class="codeph">2.00000</samp>.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="passp.htm" title="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.">Pass parameters</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="lprvl.htm" title="You can specify a length for parameter values using the LEN parameter.">Length of parameter value</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>
|
||
|
|
<div class="relinfo"><strong>Related information</strong><br />
|
||
|
|
<div><a href="../cl/call.htm">Call (CALL) command</a></div>
|
||
|
|
<div><a href="../clfinder/finder.htm">CL command finder</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|