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.

Restrictions:

1. This command is shipped with public *EXCLUDE authority, and the QSRV user profile has private authority to use the command.
2. 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.
3. 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.
4. This command cannot be used to change variables in a bound program.
5. This command cannot be used to change variables that are write-protected or within the system domain, unless the user has *SERVICE special authority.

Parameters

Keyword	Description	Choices	Notes
PTR	Pointer to be changed	Element list	Required, Positional 1
	Element 1: Program variable	Character value
	Element 2: Basing pointer variable	Values (up to 5 repetitions): Character value
SYSOBJ	System object	Single values: *NULL Other values: Qualified object name	Optional, Positional 2
	Qualifier 1: System object	Name
	Qualifier 2: Library	Name, *LIBL, *CURLIB
OBJTYPE	Object type	Character value	Optional, Positional 3
ADR	Address to be pointed to	Single values: *NULL Other values: Element list	Optional
	Element 1: Program variable	Character value
	Element 2: Basing pointer variable	Values (up to 5 repetitions): Character value
OFFSET	New offset in space	Integer	Optional
PGM	Program	Name, *DFTPGM	Optional
PTRTYPE	Pointer type	*SAME, *SYP, *SPP	Optional
RCRLVL	Recursion level	Integer, *LAST	Optional

Top

Pointer to be changed (PTR)

Specifies the pointer variable whose value is to be changed. This allows the pointer variable to point to a different address.

This is a required parameter.

Note: 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.

Element 1: Program variable

character-value

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.

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.

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.

Element 2: Basing pointer variable

character-value

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.

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.

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.

System object (SYSOBJ)

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 Pointer to be changed (PTR) parameter.

Single values

*NULL

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 Object type (OBJTYPE) parameter cannot be specified if *NULL is specified here.

Qualifier 1: System object

name

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.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

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.

name

Specify the library where the object is located.

Object type (OBJTYPE)

Specifies the object type of the system object specified in the System object (SYSOBJ) parameter to which the pointer named in the Pointer to be changed (PTR) parameter is set.

Address to be pointed to (ADR)

Specifies the program variable (if any) to which the specified space pointer is to point (that is, the program variable's address).

Single values

*NULL

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.

Element 1: Program variable

character-value

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.

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.

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.

Element 2: Basing pointer variable

character-value

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.

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.

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.

New offset in space (OFFSET)

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.

Program (PGM)

Specifies the name of the program that contains the pointer whose value is to change.

*DFTPGM

The program previously specified as the default program contains the pointer whose value is to change.

name

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.

Pointer type (PTRTYPE)

Specifies the type of pointer named in the Pointer to be changed (PTR) parameter.

Note: A high level language (HLL) pointer cannot be changed to a system pointer value.

*SAME

The type of pointer remains the same.

*SYP

The pointer type is a system pointer.

*SPP

The pointer type is a space pointer.

Recursion level (RCRLVL)

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 Recursion level (RCRLVL) parameter. Some high-level languages also allow recursive procedures. For these programs, refer to the appropriate high-level language manual for more information.

*LAST

The last (most recent) call of the specified program contains the variable to be changed.

integer

Specify the recursion level of the program that contains the variable to be changed.

Examples

CHGPTR   PTR(DATAFILPTR)  SYSOBJ(QGPL/MYFILE)  OBJTYPE(*FILE)

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.

Error messages

*ESCAPE Messages

CPF1999

Errors occurred on command.