170 lines
9.7 KiB
HTML
170 lines
9.7 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="reference" />
|
|
<meta name="DC.Title" content="Example: Writing an MI program" />
|
|
<meta name="abstract" content="This topic shows how to write a simple MI program that receives two packed-decimal parameters and returns the larger value through a third parameter." />
|
|
<meta name="description" content="This topic shows how to write a simple MI program that receives two packed-decimal parameters and returns the larger value through a third parameter." />
|
|
<meta name="DC.Relation" scheme="URI" content="MIpgmg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/qprcrtpg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="../rzatk/mitoc.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/qprcrtpg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="MIcrever.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="MIwritprog" />
|
|
<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>Example: Writing an MI program</title>
|
|
</head>
|
|
<body id="MIwritprog"><a name="MIwritprog"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Example: Writing an MI program</h1>
|
|
<div><p>This topic shows how to write a simple MI program that receives
|
|
two packed-decimal parameters and returns the larger value through a third
|
|
parameter.</p>
|
|
<div class="section"><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>
|
|
<p>This MI program demonstrates how to do the following
|
|
tasks:</p>
|
|
<ul><li>Define an external entry point</li>
|
|
<li>Define and access parameters</li>
|
|
<li>Use conditional branching</li>
|
|
<li>Assign a value to a scalar object</li>
|
|
<li>End the program</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Setting the entry point</h4><p>First the program, MI01
|
|
in this example, needs an ENTRY directive statement to designate its external
|
|
entry point. The following directive declares an unnamed (the *) external
|
|
(the EXT) entry point, which is called with a parameter list corresponding
|
|
to PARM_LIST (defined later in the source code):</p>
|
|
<pre>ENTRY * (PARM_LIST) EXT;</pre>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Setting the declare statements</h4><p><span class="keyword">i5/OS™</span> programs
|
|
typically pass parameters by reference as part of the high-level language
|
|
(HLL) calling convention. Because <span class="keyword">i5/OS</span> programs
|
|
pass by reference (that is, address and not value), the program also needs
|
|
to define three space pointers (how storage is referenced) to represent the
|
|
three parameters being passed. This is accomplished by the following directives:</p>
|
|
<pre>DCL SPCPTR ARG1@ PARM;
|
|
DCL SPCPTR ARG2@ PARM;
|
|
DCL SPCPTR RESULT@ PARM;</pre>
|
|
<p>To associate these three space pointers with the parameters
|
|
being passed to the program, the following operand list (OL) is declared:</p>
|
|
<pre>DCL OL PARM_LIST /* Name of OL is PARM_LIST */
|
|
(ARG1@, /* The first parameter */
|
|
ARG2@, /* The second parameter */
|
|
RESULT@) /* The third parameter */
|
|
PARM EXT; /* External parameter list */</pre>
|
|
<p>The names ARG1@, ARG2@, RESULT@, and PARM_LIST are chosen by
|
|
you and are not mandated by the system. You can choose any valid name for
|
|
any object data element. For a definition of what constitutes a valid name,
|
|
see "Name" in the Program syntax topic of the Create Program (QPRCRTPG) API.</p>
|
|
<p>Now
|
|
that the program has established addressability (the space pointers) to the
|
|
three parameters, the program needs to declare how to map (or view) the storage
|
|
addressed. The following declarations define the storage addressed (the BAS
|
|
argument) by the three space pointer parameters as being packed-decimal (PKD)
|
|
scalar data objects (DD) with 15 digits, 5 digits being to the right of the
|
|
decimal point:</p>
|
|
<pre>DCL DD ARG1 PKD(15,5) BAS(ARG1@);
|
|
DCL DD ARG2 PKD(15,5) BAS(ARG2@);
|
|
DCL DD RESULT PKD(15,5) BAS(RESULT@);</pre>
|
|
<p>The names ARG1, ARG2, and RESULT are chosen arbitrarily, but,
|
|
for ease of reading, are similar to the basing space pointers ARG1@, ARG2@,
|
|
and RESULT@. The declarations of packed 15,5 are used for consistency with
|
|
CL. The declared type and size could be of any other valid type and size.
|
|
The true requirement is that the calling program and the MI program agree
|
|
on the type and size.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Starting the instruction stream</h4><p>With all the needed
|
|
declarations now done, the instruction stream definition, where the program
|
|
will compare the numeric values (CMPNV instruction) of parameters one and
|
|
two, is started:</p>
|
|
<pre> CMPNV(B) ARG1,ARG2 / LO(ITS2);</pre>
|
|
<p>The program then branches (the (B) extender to CMPNV) to label
|
|
ITS2 if ARG1 is less than ARG2 (the /LO branch target).</p>
|
|
<div class="note"><span class="notetitle">Note:</span> MI instructions
|
|
such as CMPNV are defined in the iSeries™ Machine Interface instructions.
|
|
Pervasive instruction extenders such as branch (B) and target keywords (LO,
|
|
HI, EQ, and so on) are defined under Instruction Statement, which is a subheading
|
|
in the Program syntax topic of the Create Program (QPRCRTPG) API.</div>
|
|
<p>If
|
|
ARG1 is not low (LO) when compared to ARG2, the next MI instruction in the
|
|
source stream is run. When the next MI instruction is run, it copies the numeric
|
|
value (CPYNV instruction) of ARG1 to RESULT and, following that, branches
|
|
to label RETURN:</p>
|
|
<pre> CPYNV RESULT,ARG1;
|
|
B RETURN;</pre>
|
|
<p>If ARG2 was greater than ARG1, the CPYNV instruction at label
|
|
ITS2 is run, setting RESULT to the value of ARG2:</p>
|
|
<pre>ITS2: CPYNV RESULT,ARG2;</pre>
|
|
<p>The
|
|
program has now finished processing and ends:</p>
|
|
<pre>RETURN: RTX *;
|
|
PEND;</pre>
|
|
<p>The previous return external (RTX) instruction is not needed
|
|
because it is implied by the PEND directive. The RTX instruction is included
|
|
to add clarity to the program flow.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">MI01 program complete code example</h4><p>Put all together,
|
|
the program looks like this:</p>
|
|
<pre>/********************************************************************/
|
|
/********************************************************************/
|
|
/* */
|
|
/* Program Name: MI01 */
|
|
/* */
|
|
/* Programming Language: MI */
|
|
/* */
|
|
/* Description: Return the larger of two packed arguments. */
|
|
/* */
|
|
/* */
|
|
/* Header Files Included: None */
|
|
/* */
|
|
/* */
|
|
/********************************************************************/
|
|
ENTRY * (PARM_LIST) EXT;
|
|
DCL SPCPTR ARG1@ PARM;
|
|
DCL SPCPTR ARG2@ PARM;
|
|
DCL SPCPTR RESULT@ PARM;
|
|
DCL OL PARM_LIST
|
|
(ARG1@,
|
|
ARG2@,
|
|
RESULT@)
|
|
PARM EXT;
|
|
DCL DD ARG1 PKD(15,5) BAS(ARG1@);
|
|
DCL DD ARG2 PKD(15,5) BAS(ARG2@);
|
|
DCL DD RESULT PKD(15,5) BAS(RESULT@);
|
|
CMPNV(B) ARG1,ARG2 / LO(ITS2);
|
|
CPYNV RESULT,ARG1;
|
|
B RETURN;
|
|
ITS2: CPYNV RESULT,ARG2;
|
|
RETURN: RTX *;
|
|
PEND;</pre>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="MIpgmg.htm" title="Provides information about creating machine interface (MI) programs.">Machine interface programming</a></div>
|
|
</div>
|
|
<div class="relref"><strong>Related reference</strong><br />
|
|
<div><a href="../apis/qprcrtpg.htm">Program syntax</a></div>
|
|
<div><a href="../rzatk/mitoc.htm">iSeries Machine Interface instructions</a></div>
|
|
<div><a href="MIcrever.htm" title="This topic discusses how to create an MI version of the CLCRTPG program that can be used to create MI programs. This program is called MICRTPG.">Creating an MI version of CLCRTPG</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |