344 lines
16 KiB
HTML
344 lines
16 KiB
HTML
|
|
||
|
|
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<title>Change Pointer (CHGPTR)</title>
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body bgcolor="white">
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<a name="CHGPTR.Top_Of_Page"></a>
|
||
|
|
<h2>Change Pointer (CHGPTR)</h2>
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
|
||
|
|
<b>Threadsafe: </b>No
|
||
|
|
</td>
|
||
|
|
<td valign="top" align="right">
|
||
|
|
<a href="#CHGPTR.PARAMETERS.TABLE">Parameters</a><br>
|
||
|
|
<a href="#CHGPTR.COMMAND.EXAMPLES">Examples</a><br>
|
||
|
|
<a href="#CHGPTR.ERROR.MESSAGES">Error messages</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<div> <a name="CHGPTR"></a>
|
||
|
|
<p>The Change Pointer (CHGPTR) command changes the value of a pointer variable in a program. The value of the program pointer specified can be changed to point to a new system object, to a new space pointer address, or to a new offset within a space object. This command is not normally used in high-level language programs.
|
||
|
|
</p>
|
||
|
|
<p><b>Restrictions:</b>
|
||
|
|
</p>
|
||
|
|
<ol>
|
||
|
|
<li>This command is shipped with public *EXCLUDE authority, and the QSRV user profile has private authority to use the command.
|
||
|
|
</li>
|
||
|
|
<li>This command is valid only for changing program variables that are used as pointers and is valid only in debug mode. To start debug mode, refer to the STRDBG (Start Debug) command.
|
||
|
|
</li>
|
||
|
|
<li>This command cannot be used if the user is servicing another job, and that job is on a job queue, or is being held, suspended, or ended.
|
||
|
|
</li>
|
||
|
|
<li>This command cannot be used to change variables in a bound program.
|
||
|
|
</li>
|
||
|
|
<li>This command cannot be used to change variables that are write-protected or within the system domain, unless the user has *SERVICE special authority.
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
|
||
|
|
<div>
|
||
|
|
<h3><a name="CHGPTR.PARAMETERS.TABLE">Parameters</a></h3>
|
||
|
|
<table border="1" cellpadding="4" cellspacing="0">
|
||
|
|
<!-- col1="10" col2="15" col3="30" col4="10" -->
|
||
|
|
<tr>
|
||
|
|
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
|
||
|
|
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
|
||
|
|
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
|
||
|
|
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="3"><a href="#CHGPTR.PTR"><b>PTR</b></a></td>
|
||
|
|
<td valign="top">Pointer to be changed</td>
|
||
|
|
<td valign="top"><i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="3">Required, Positional 1</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Program variable</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 2: Basing pointer variable</td>
|
||
|
|
<td valign="top">
|
||
|
|
Values (up to 5 repetitions): <i>Character value</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="3"><a href="#CHGPTR.SYSOBJ"><b>SYSOBJ</b></a></td>
|
||
|
|
<td valign="top">System object</td>
|
||
|
|
<td valign="top">Single values: *NULL<br>Other values: <i>Qualified object name</i></td>
|
||
|
|
<td valign="top" rowspan="3">Optional, Positional 2</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Qualifier 1: System object</td>
|
||
|
|
<td valign="top"><i>Name</i></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top">Qualifier 2: Library</td>
|
||
|
|
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top"><a href="#CHGPTR.OBJTYPE"><b>OBJTYPE</b></a></td>
|
||
|
|
<td valign="top">Object type</td>
|
||
|
|
<td valign="top"><i>Character value</i></td>
|
||
|
|
<td valign="top">Optional, Positional 3</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="3"><a href="#CHGPTR.ADR"><b>ADR</b></a></td>
|
||
|
|
<td valign="top">Address to be pointed to</td>
|
||
|
|
<td valign="top">Single values: *NULL<br>Other values: <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="3">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Program variable</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 2: Basing pointer variable</td>
|
||
|
|
<td valign="top">
|
||
|
|
Values (up to 5 repetitions): <i>Character value</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#CHGPTR.OFFSET"><b>OFFSET</b></a></td>
|
||
|
|
<td valign="top">New offset in space</td>
|
||
|
|
<td valign="top"><i>Integer</i></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#CHGPTR.PGM"><b>PGM</b></a></td>
|
||
|
|
<td valign="top">Program</td>
|
||
|
|
<td valign="top"><i>Name</i>, <b><u>*DFTPGM</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#CHGPTR.PTRTYPE"><b>PTRTYPE</b></a></td>
|
||
|
|
<td valign="top">Pointer type</td>
|
||
|
|
<td valign="top"><b><u>*SAME</u></b>, *SYP, *SPP</td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#CHGPTR.RCRLVL"><b>RCRLVL</b></a></td>
|
||
|
|
<td valign="top">Recursion level</td>
|
||
|
|
<td valign="top"><i>Integer</i>, <b><u>*LAST</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<div> <a name="CHGPTR.PTR"></a>
|
||
|
|
<h3>Pointer to be changed (PTR)</h3>
|
||
|
|
<p>Specifies the pointer variable whose value is to be changed. This allows the pointer variable to point to a different address.
|
||
|
|
</p>
|
||
|
|
<p>This is a required parameter.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<b>Note: </b>If the pointer variable is an HLL pointer (which was declared in the source for a high-level language program), a space or null value can be assigned to the pointer, or the offset of the pointer can be changed, but the variable cannot be set with a system pointer value. If you specify a pointer which is not a HLL pointer, or if you use the ODV number for a pointer which is an HLL pointer, this restriction does not apply. More information on testing and debugging at the machine interface level is in the CL information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
||
|
|
</p>
|
||
|
|
<p><b>Element 1: Program variable</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the name of the pointer variable whose value is to be changed. The name must be enclosed in apostrophes if it contains special characters.
|
||
|
|
<p>If the pointer (program variable) is an array, the subscripts representing the element in the array to be changed must be specified. Up to 132 characters may be specified for this pointer (program variable) entry. This includes any qualifiers, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are not used. An integer, MI ODV number, or a numeric variable name can be specified for a subscript.
|
||
|
|
</p>
|
||
|
|
<p>For more information, refer to "Parameter values used for testing and debugging" in "CL concepts and reference" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 2: Basing pointer variable</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the name of a basing pointer variable. In some languages, the pointer (program variable) can be based on a pointer variable. This set of values allows you to explicitly specify up to 5 basing pointers for the pointer that is to change. Each basing pointer name must be enclosed in apostrophes if it contains special characters.
|
||
|
|
<p>If the basing pointer is an array, the subscripts representing an element in the array must be specified. Up to 132 characters can be specified for a basing pointer name. This includes any qualification, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, or a numeric variable name can be specified for a subscript.
|
||
|
|
</p>
|
||
|
|
<p>For more information, refer to "Parameter values used for testing and debugging" in "CL concepts and reference" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.SYSOBJ"></a>
|
||
|
|
<h3>System object (SYSOBJ)</h3>
|
||
|
|
<p>Specifies that the pointer is set to either a system pointer or to a space pointer that addresses a particular system object, or to a null pointer value. This parameter cannot be specified when an HLL pointer is specified for the <b>Pointer to be changed (PTR)</b> parameter.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*NULL</b></dt>
|
||
|
|
<dd>The system pointer is set to a null; that is, it no longer points to any system object nor does it have a pointer type. The <b>Object type (OBJTYPE)</b> parameter cannot be specified if *NULL is specified here.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Qualifier 1: System object</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the object to which the system pointer is set. The pointer variable is set to either a system pointer value or a space pointer value.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Qualifier 2: Library</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*LIBL</u></b></dt>
|
||
|
|
<dd>All libraries in the library list for the current thread are searched until the first match is found.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*CURLIB</b></dt>
|
||
|
|
<dd>The current library for the job is used to locate the object. If no current library entry exists in the library list, QGPL is used.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the library where the object is located.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.OBJTYPE"></a>
|
||
|
|
<h3>Object type (OBJTYPE)</h3>
|
||
|
|
<p>Specifies the object type of the system object specified in the <b>System object (SYSOBJ)</b> parameter to which the pointer named in the <b>Pointer to be changed (PTR)</b> parameter is set.
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.ADR"></a>
|
||
|
|
<h3>Address to be pointed to (ADR)</h3>
|
||
|
|
<p>Specifies the program variable (if any) to which the specified space pointer is to point (that is, the program variable's address).
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*NULL</b></dt>
|
||
|
|
<dd>The space pointer is set to a null; it no longer points to the address of any space object nor does it have a pointer type.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Program variable</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the name of the program variable to which the space pointer is set. The name must be enclosed in apostrophes if it contains special characters.
|
||
|
|
<p>If an array is specified without any subscripts, the pointer is set to the address of the first element in the array. Up to 132 characters may be specified for this program variable entry. This includes any qualifiers, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, or numeric variable name can be specified for a subscript.
|
||
|
|
</p>
|
||
|
|
<p>For more information, refer to "Parameter values used for testing and debugging" in "CL concepts and reference" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 2: Basing pointer variable</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the name of a basing pointer variable. In some languages, the program variable may be based on a pointer variable. This set of values allows you to explicitly specify up to 5 basing pointers for the variable that is addressed. Each basing pointer name must be enclosed in apostrophes if it contains special characters.
|
||
|
|
<p>If the basing pointer is an array, the subscripts representing an element in the array must be specified. Up to 132 characters can be specified for a basing pointer name. This includes any qualifiers, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, MI ODV number, or a numeric variable name can be specified for a subscript.
|
||
|
|
</p>
|
||
|
|
<p>For more information, refer to "Parameter values used for testing and debugging" in "CL concepts and reference" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.OFFSET"></a>
|
||
|
|
<h3>New offset in space (OFFSET)</h3>
|
||
|
|
<p>Specifies the value to which the offset portion of the specified space pointer is set. Specify the number of bytes from the start of the space object that the space pointer is set to.
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.PGM"></a>
|
||
|
|
<h3>Program (PGM)</h3>
|
||
|
|
<p>Specifies the name of the program that contains the pointer whose value is to change.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*DFTPGM</u></b></dt>
|
||
|
|
<dd>The program previously specified as the default program contains the pointer whose value is to change.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the program that contains the pointer whose value is to change. The same name must already have been specified in the Start Debug (STRDBG) or Add Program (ADDPGM) command.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.PTRTYPE"></a>
|
||
|
|
<h3>Pointer type (PTRTYPE)</h3>
|
||
|
|
<p>Specifies the type of pointer named in the <b>Pointer to be changed (PTR)</b> parameter.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<b>Note: </b>A high level language (HLL) pointer cannot be changed to a system pointer value.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*SAME</u></b></dt>
|
||
|
|
<dd>The type of pointer remains the same.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*SYP</b></dt>
|
||
|
|
<dd>The pointer type is a system pointer.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*SPP</b></dt>
|
||
|
|
<dd>The pointer type is a space pointer.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="CHGPTR.RCRLVL"></a>
|
||
|
|
<h3>Recursion level (RCRLVL)</h3>
|
||
|
|
<p>Specifies which recursion level of the program contains the variable whose value is to be changed. Changes made to static variables automatically affect all recursion levels. Recursion level 1 is the first (or earliest) call of the program, recursion level 2 is the second call of the program, and so on to the last (most recent) recursion level in the stack. For example, if program A calls program B, then program B calls program A, a new recursion level of program A is formed. If the first call of program A contains the variable to be changed, a value of 1 must be specified for the <b>Recursion level (RCRLVL)</b> parameter. Some high-level languages also allow recursive procedures. For these programs, refer to the appropriate high-level language manual for more information.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*LAST</u></b></dt>
|
||
|
|
<dd>The last (most recent) call of the specified program contains the variable to be changed.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>integer</i></b></dt>
|
||
|
|
<dd>Specify the recursion level of the program that contains the variable to be changed.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
<div><h3><a name="CHGPTR.COMMAND.EXAMPLES">Examples</a> </h3>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
CHGPTR PTR(DATAFILPTR) SYSOBJ(QGPL/MYFILE) OBJTYPE(*FILE)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command changes the value of the pointer DATAFILPTR that is used in the default program in the debug mode. The pointer value is changed to point to the file called MYFILE, which is stored in the QGPL library.
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
<div><h3><a name="CHGPTR.ERROR.MESSAGES">Error messages</a> </h3>
|
||
|
|
<p><b><u>*ESCAPE Messages</u></b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>CPF1999</b></dt>
|
||
|
|
<dd>Errors occurred on command.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#CHGPTR.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|