CHGHLLPTR (Change High-Level Language Pointer)

CHGHLLPTR Command syntax diagram

 

Purpose

The Change High Level Language Pointer (CHGHLLPTR) command allows the user to change or copy a pointer variable declared in a high-level language (HLL) program.

The following functions can be requested:

HLL pointers are pointer variables that are declared in the source of an HLL program; they are contrasted with internal compiler-created pointers. Compiler-created pointers are pointer variables that are declared in the machine-interface (MI) program, by a compiler, to support various processing functions. Not all languages allow the user to declare HLL pointers.

 

Restrictions

  1. This command is valid only in debug mode. To start debug mode, refer to the STRDBG (Start Debug) command.

  2. 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.

  3. This command cannot be used to change variables in a bound program.

  4. This command cannot be used to change variables that are write-protected or within the system domain, unless the user has *SERVICE special authority.

 

Required Parameters

PTR
Specifies the name of the pointer (program variable) whose value is being changed, allowing the pointer to point to a different address.

Element 1: Program Variables

'program-variable': Specify the name of the pointer variable whose value is being changed. The pointer variable must be an HLL pointer (HLLPTR). A machine-interface object-definition-table-vector (MI ODV) number cannot be specified for the variable name, even though the variable that it defines is an HLL pointer. The name must be enclosed in apostrophes if it contains special characters.

If the pointer (program variable) is in 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 used. An integer, MI ODV number, or numeric variable name can be specified for a subscript. For more information on changing program variables during testing, refer to the CL Programming book and parameter values used for testing and debugging.

Some examples are: 

PTR('PTR_ARRAY(2)')
PTR(P1)

Element 2: Basing Pointers

'basing-pointer': Specify up to five basing pointers. In some languages, the pointer (program-variable) may be based on a pointer variable. This set of values allows the user to specify the basing pointers for the pointer to be changed. The basing pointers must be HLL pointers (HLLPTR). An MI ODV number cannot be specified for the name, even though the pointer that defines it is an HLL pointer. 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, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. For more information on the basing pointer value, refer to parameter values used for testing and debugging.

Some examples are: 

PTR('P@(B,5)'  'Q@(I)')
PTR(PTR1 (BASEPTRA BASEPTRB))
REFPTR
Specifies the name of the pointer (program variable) whose value is being copied into the pointer identified in the PTR parameter.

Element 1: Program Variables

'program-variable': Specify the name of the pointer variable whose value is copied into the specified pointer. The pointer variable must be an HLL pointer (HLLPTR). An MI ODV number cannot be specified for the variable name, even though the variable that it defined is an HLL pointer. The name must be enclosed in apostrophes if it contains special characters. If the pointer (program variable) is in an array, the subscripts representing the element in the array to be copied 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 used. An integer, MI ODV number, or numeric variable name can be specified for a subscript.

Some examples are: 

REFPTR('PRT1(2,3)')
REFPTR(C2PTR)

Element 2: Basing Pointers

'basing-pointer': Specify up to five basing pointers. The pointer (program variable) may be based on a pointer variable. This set of values allows the user to specify the basing pointers for the pointer to be copied. The basing pointer must be an HLL pointer (HLLPTR). An MI ODV number cannot be specified for the name, even though the pointer that defines it is an HLL pointer. 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, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. For more information on the basing-pointer value, refer to parameter values used for testing and debugging.

Some examples are: 

REFPTR('P@(B,5)'  'Q@(I)')
REFPTR(PRT1 (BASEPTRA 'Q@(/1F)'))
ADR
Specifies the name of the program variable, if any, to which the specified HLL pointer is to point.

*NULL: The HLL pointer is set to null; it no longer points to the address of any space object, and it no longer contains a space pointer or any type of pointer value.

Element 1: Program Variables

'program-variable': Specify the name of the variable to which the HLL pointer is to point. An HLL variable name must be entered; an MI ODV number cannot be used. The name must be enclosed in apostrophes if it contains special characters. If an array is specified without 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 on the program-variable value, refer to parameter values used for testing and debugging.

Some examples are: 

ADR('VAR1(2,3)')
ADR(ARRAY2)

Element 2: Basing Pointers

'basing-pointer': Specify up to five basing pointers. In some languages, the program-variable may be based on a pointer variable. This set of values allows the user to specify the basing pointers for the variables to be addressed. The basing pointers must be HLL pointers (HLLPTR). An MI ODV number cannot be specified for the name, even though the pointer that defines it is an HLL pointer. 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, subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. For more information on the basing-pointer value, refer to parameter values used for testing and debugging.

Some examples are: 

ADR('VAR(2,5)' 'PGMPTR(5)')
ADR(VAR5 (BASEPTRA BASEPTRB))

 

Optional Parameters

PGM
Specifies the name of the program that contains the pointer whose value is being changed.

*DFTPGM: The program currently specified as the default program contains the pointer whose value is changed.

program-name: Specify the name of the program that contains the pointer whose value is being changed. The name must already have been specified in the STRDBG or Add Program (ADDPGM) command.

RCRLVL
Specifies which recursion level of the program contains the pointer whose value is being 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 recursion of the program, and so on to the last (most recent) recursion level in the stack. For example, if program A calls program B, and then program B calls program A, a new recursion level of program A is formed. If the first recursion level of program A contains the pointer being changed, RCRLVL(1) must be specified. Some high-level languages also allow recursive procedures. More information on these programs is in the appropriate high-level language manual.

*LAST: The last, most recent, call of the specified program contains the pointer being changed.

recursion-level-number: Specify the number of the recursion level of the program containing the pointer being changed.

Examples for CHGHLLPTR

Example 1: Setting a Pointer to a Variable Address 

CHGHLLPTR  PTR(STACKPTR)  ADR(FIRSTELEM)

This command sets the pointer STACKPTR to the address of the variable FIRSTELEM.

Example 2: Copying the Value of a Pointer 

CHGHLLPTR  PTR(NEXT@)  REFPTR(CURRENT@)

This command copies the value of the pointer CURRENT@ into the pointer NEXT@. The value copied could be a null pointer.

Error messages for CHGHLLPTR

*ESCAPE Messages

None.