Change Program Variable (CHGPGMVAR)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Change Program Variable (CHGPGMVAR) command changes the value of a variable in a program being debugged. Only string (character or bit) and numeric variables can be changed using this command. A portion of a character string or bit string can be changed; the length of the data to be changed is the length of the data specified on the New value (VALUE) parameter.
Note: Depending on where the variable is allocated, the duration of a change varies. For a variable in machine-interface (MI) static storage, the change lasts while the program is active. For an automatic variable, the change lasts until the call of the program is ended. Static variables are allocated either in MI static storage or in spaces controlled by language-dependent rules.
Restrictions:
- You can use this command only in debug mode. To start debug mode, refer to the Start Debug (STRDBG) command.
- You cannot use this command if you are servicing another job, and that job is on a job queue, or is being held, suspended, or ended.
- You cannot use this command to change variables in a bound program.
- You cannot use this command to change variables that are write-protected or within the system domain, unless the user has service (*SERVICE) special authority.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| PGMVAR | Program variables | Element list | Required, Positional 1 |
| Element 1: Program variable | Character value | ||
| Element 2: Basing pointer variable | Values (up to 5 repetitions): Character value | ||
| VALUE | New value | Not restricted | Required, Positional 2 |
| PGM | Program | Name, *DFTPGM | Optional |
| START | Char output start position | Integer, 1 | Optional, Positional 3 |
| RCRLVL | Recursion level | Integer, *LAST | Optional |
| Top |
Program variables (PGMVAR)
Specifies the program variable to be changed in a high-level language (HLL) or machine instruction (MI) program.
This is a required parameter.
Element 1: Program variable
- character-value
- Specify the name of the program variable to be changed. If the variable name contains special characters, it must be enclosed in apostrophes.
If the program variable is an array, the subscripts representing the elements in the array can be specified. If an array name is specified without any subscripts, all of the array elements are recorded. A single-dimensional cross-section can also be specified. Up to 132 characters may be specified for this program variable entry. This includes any qualifiers, subscripts, blanks, parentheses, and commas. It does not include the enclosing apostrophes when special characters are used. An integer, machine-interface object-definition-table-vector (MI ODV) number, asterisk (single-dimensional cross-section), 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 topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/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 as many as 5 basing pointers for the variable to be recorded. 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, 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 topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
| Top |
New value (VALUE)
Specifies the new value for the program variable. Rules for specifying values depend on the variable type.
This is a required parameter.
| Top |
Program (PGM)
Specifies the name of the program that contains the program variable whose value is to change.
- *DFTPGM
- The program previously specified as the default program contains the variable to be changed.
- name
- Specify the name of the program that contains the variable to change. The same name must already have been specified on the Start Debug (STRDBG) or Add Program (ADDPGM) command.
| Top |
Char output start position (START)
Specifies, for string variables only, the starting position in the string from which its value is to change. For a bit string, the value specifies the starting bit position; for a character string, the value specifies the starting character position.
- 1
- The first position of the program variable is the starting position in the string to change.
- integer
- Specify the position number in the program variable that specifies the first position to change in the string. The starting position number must not be greater than the length of the string, except that a value of 1 for the START parameter is allowed if the maximum length for a string is zero. The length determined by the New value (VALUE) parameter, plus the value supplied for the START parameter minus one, must not be greater than the maximum string length.
Varying length strings have rules affecting the validity and meaning of the START parameter.
| Top |
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.
| Top |
Examples
Example 1: Changing the Program Variable
DCL VAR(&AMT) TYPE(*DEC) LEN(5 2)
:
CHGPGMVAR PGMVAR('&AMT') VALUE(16.2)
The first command, which is used in a CL program, declares the CL variable &AMT as a five-position decimal value having a 3-digit integer and a 2-digit fraction. The Change Program Variable (CHGPGMVAR) command is used to change the value of &AMT to 16.20. If VALUE is coded as 16 or 16.00, the value accepted is 16.00; if -16 is coded, the value accepted is -16.00. However, if 1600 is coded, an error occurs because the system assumes that, if no decimal point is coded, it is always on the right of the last digit coded.
Example 2: Changing a Value in a Specific Position
CHGPGMVAR PGMVAR(PARTNO) VALUE('56') START(4)
This command changes, starting in position 4, the program variable PARTNO to '56'.
| Top |
| Top |