CHGPGM (Change Program)

CHGPGM Command syntax diagram

 

Purpose

The Change Program (CHGPGM) command changes the attributes of a program without requiring that it be recompiled. The user can also force re-creation of a program even if the attributes being specified are the same as the current attributes.

Restrictions:

  1. The user must have *USE authority for the library for the program that is being changed.

  2. The user must have *USE and *OBJMGT authority for the program that is being changed.

  3. The user must have *USE, *DLT, and *ADD authority for the library to change the optimization attribute (OPTIMIZE), performance collection attribute (ENBPFRCOL), profiling data attribute (PRFDTA), Licensed Internal Code options (LICOPT), enable teraspace storage (TERASPACE), or to force program re-creation by specifying FRCCRT(*YES).

  4. Only the program owner, or a user with *SECADM and *ALLOBJ authority, can change the user profile attribute (USRPRF) or the use adopted authority attribute (USEADPAUT).

  5. Programs in library QSYS and QGDDM cannot be changed.

  6. The STGMDL of the service program and all bound modules must be *SNGLVL to change a program to TERASPACE(*NO).

Other jobs running the program may fail if the Optimize program prompt (OPTIMIZE parameter), the Use adopted authority prompt (USEADPAUT parameter), the Enable performance collection prompt (ENBPFRCOL parameter), the Profiling data prompt (PRFDTA parameter), the User profile prompt (USRPRF parameter), or Licensed Internal Code Options (LICOPT), or enable teraspace storage (TERASPACE parameter) are changed, or program re-creation is forced by specifying FRCCRT(*YES).

 

Required Parameters

PGM
Specifies the programs whose attributes are being changed. *USRLIBL cannot be specified or defaulted for the library qualifier when a generic name or *ALL is specified for the program qualifier.

The name of the program can be qualified by one of the following library values:

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

library-name: Specify the name of the library to be searched.

*ALL: All programs in the specified library to which the user has some authority (for example, *USE authority) are selected for change.

program-name: Specify the name of the programs whose attributes are being changed.

generic*-program-name: Specify the generic name of the program. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. See generic names for additional information.

 

Optional Parameters

OPTIMIZE
Specifies whether the program is optimized. This parameter removes redundant instructions from the specified programs. Changing the current optimization level of an Integrated Language Environment (ILE) program causes the system to re-create an ILE program with the new optimization level.

*SAME: The value does not change.

*YES: The program is at the most optimized level available for the release and language the program was created for (TGTRLS parameter when the program was created). In most cases, optimized programs make more efficient use of system resources. Specifying OPTIMIZE(*YES) for ILE programs has the same effect as specifying OPTIMIZE(40).

*NO: The program is not optimized. For ILE programs at this optimization level, variables can be displayed and changed while debugging.

40: This level includes all the optimizations performed at optimization level 30 (*FULL). In addition, it includes optimization that disables call and instruction tracing. Thus, tracing of modules created at this optimization level cannot be done. Specifying OPTIMIZE(40) for OPM programs has the same effect as specifying OPTIMIZE(*YES).

*FULL or 30: More optimization is performed in addition to those performed at optimization level 20 (*BASIC). Variables cannot be changed but can be displayed while the program is being debugged. However, the displayed value of the variable during debugging may not be its actual value. Specifying OPTIMIZE(*FULL) for OPM programs has no effect; a diagnostic message will be signaled.

*BASIC or 20: For ILE programs, some optimization is performed on ILE programs. When debugging ILE programs at this optimization level, variables may be displayed, but the displayed value may not be the current value. Variables can also be changed but using the variables changed at this level may cause unexpected results. An informational message is sent and no optimization is performed when OPTIMIZE(*BASIC) is specified for original program model (OPM) programs.

*NONE or 10: This value is identical to *NO.

Note: The Change Program (CHGPGM) command must re-create the program to optimize the program. To be eligible for re-creation, OPM programs must be observable and ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

USRPRF
Specifies whether the authority checking done while this program is running includes only the user who is running the program (*USER) or both the user running the program and the program owner (*OWNER). The profiles of the program user or both the program user and the program owner are used to control which objects can be used by the program, including the authority the program has for each object. Only the program owner or a user with QSECOFR authority can change the user profile attribute.

*SAME: The value does not change.

*USER: The program runs under the user profile of the program's user.

*OWNER: The user profiles of both the program's owner and the program's user are used when the program is processed. The collective sets of object authority in both user profiles are used to find and access objects during program processing. Authority from the owning user profile's group profile is not included in the authority for the running program.

Note: The Change Program (CHGPGM) command must re-create the program to change the user profile. To be eligible for re-creation, OPM programs must be observable and ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

USEADPAUT
Specifies whether program adopted authority from previous programs in the call stack will be used as a source of authority when this program is running.

*SAME: The value does not change.

*YES: Program adopted authority from previous call levels is used when this program is running.

*NO: Program adopted authority from previous call levels is not used when this program is running.

Note: The Change Program (CHGPGM) command must re-create the program to change the "Use adopted authority" attribute. To be eligible for re-creation, OPM programs must be observable and ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

RMVOBS
Specifies whether the observable information associated with programs is removed.

*SAME: The value does not change.

*ALL: All of the observable information associated with the program is removed, if possible. If the program requires the observable information to ensure that it runs correctly, that information is not removed. *ALL observability is required to convert OPM programs to a different hardware technology. For example, between CISC (Complex Instruction Set Computer) and RISC (Reduced Instruction Set Computer) technology.

Notes:

  1. If block order profiling data has previously been applied to this ILE program, specifying *ALL on the RMVOBS parameter will also remove *BLKORD observability.

  2. *ALL cannot be specified if the ILE program is enabled to collect profiling data.

  3. Removing observability from OPM programs compiled with OPTION(*LSTDBG) does not completely remove the debugging information. The program must be recompiled with OPTION(*NOLSTDBG) to completely remove all of the debugging information.

  4. OPM CL programs created with ALWRTVSRC(*YES) can have their CL source retrieved using the RTVCLSRC (Retrieve CL Source) after observability has been removed. The program must be recompiled with ALWRTVSRC(*NO) to remove the source from the program.

*NONE: None of the observable information associated with the program is removed.

*DBGDTA: Information is removed from an ILE program to allow the program to be debugged. An informational message is sent and no observability is removed when RMVOBS(*DBGDTA) is specified for original program model (OPM) programs.

*CRTDTA: Information is removed from an ILE program to allow the program to be re-created, to change the optimization level, to change the performance collection attribute, or to change the profiling data attribute. An informational message is sent and no observability is removed when RMVOBS(*CRTDTA) is specified for original program model (OPM) programs.

Notes:

  1. If block order profiling data has previously been applied to this ILE program, specifying *CRTDTA on the RMVOBS parameter will also remove *BLKORD observability.

  2. *CRTDTA cannot be specified if the ILE program is enabled to collect profiling data.

  3. *CRTDTA observability is required to convert ILE programs to a different hardware technology. For example, between CISC (Complex Instruction Set Computer) and RISC (Reduced Instruction Set Computer) technology.

  4. If the ILE program was created for a release earlier than V3R6M0, and is currently in RISC format or FRCCRT(*YES) is specified, removing *CRTDTA will cause the ILE program to no longer be able to be saved for a release earlier than V3R6M0.

*BLKORD: Information is removed from an ILE program that allows the system to re-apply block order profiling data when the program is re-created. An informational message is sent and no observability is removed when RMVOBS(*BLKORD) is specified for original program model (OPM) programs.

*PRCORD: Information is removed from an ILE program that allows the system to re-apply procedure order profiling data when the program is re-created or updated. An informational message is sent and no observability is removed when RMVOBS(*PRCORD) is specified for original program model (OPM) programs.

ENBPFRCOL
Specifies whether collection of performance data is enabled. Collection of this type of performance data can be enabled only for ILE programs.

*SAME: The value does not change.

*NONE or *PEP: Performance data is collected for the Program Entry Procedure entry and exit. There are no entry or exit hooks in the module's internal procedures and no precall or postcall hooks around calls to other procedures.

Element 1: Collection level

*FULL:
Performance data is collected for procedure entry and exit. Performance data is also collected before and after calls to external procedures.

*ENTRYEXIT:
Performance data is collected for procedure entry and exit.

Element 2: Procedures

*ALLPRC:
Performance data is collected for all procedures. This is useful to capture information on all procedures.

*NONLEAF:
Performance data is collected for procedures that are not leaf procedures and for the PEP. This is useful to capture information on most routines but not at the expense of destroying the 'leaf-ness' of the leaf procedure.

Note: The Change Program (CHGPGM) command must re-create the program to enable or disable collection of performance data. To be eligible for re-creation, the program must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program has all creation data.

PRFDTA
Specifies the profiling data attribute for ILE programs. An informational message is sent and *SAME is used if a value other than *SAME is specified for the PRFDTA parameter for original program model (OPM) programs.

*SAME: The value does not change.

*NOCOL: The collection of profiling data is not enabled and profiling data is not applied.

*COL: The collection of profiling data is enabled.

Note: Specifying *COL will remove all applied profiling data if the ILE program has profiling data applied.

*CLR: All previously collected profiling data is discarded. The program remains enabled to collect profiling data.

*APYBLKORD: Block order profiling data is applied to every module bound into this ILE program previously enabled to collect profiling data. The collection of profiling data is no longer enabled.

*APYPRCORD: Block order and procedure order profiling data is applied. The collection of profiling data is no longer enabled.

*APYALL: Block order and procedure order profiling data is applied. The collection of profiling data is no longer enabled.

Note: The Change Program (CHGPGM) command must re-create the program to change the profiling data attribute. To be eligible for re-creation, the program must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program has all creation data.

TERASPACE
This parameter allows the teraspace storage enablement to be changed to the specified value. Changing the enable teraspace storage parameter to any value other than *SAME causes the system to re-create the program.

*SAME: The teraspace storage enablement does not change.

*NO: The teraspace storage enablement is changed to no. If it is a ILE program, the teraspace storage enablement of the eligible bound modules is changed to no. A bound module must be single level storage model to be changed to TERASPACE(*NO).

*YES: The teraspace storage enablement of the program is changed. If it is a ILE program, the teraspace storage enablement of the eligible bound modules is changed to yes. A bound module must be at least V4R4M0 or later to be changed to TERASPACE(*YES).

Note: The Change Program (CHGPGM) command must re-create the program to change the teraspace enablement. To be eligible for re-creation, OPM programs must be observable and ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

LICOPT
This parameter allows individual Licensed Internal Code compile-time options to be selected, and is intended for the advanced programmer who understands the potential benefits and drawbacks of each selected type of compiler option. Changing the Licensed Internal Code options of an Integrated Language Environment (ILE) program to any value other than *SAME causes the system to re-create the ILE program with the specified Licensed Internal Code options.

*SAME: If the program object is re-created, the existing Licensed Internal Code compile-time options are input to object re-creation. Otherwise, the Licensed Internal Code compile-time options do not change.

Licensed-Internal-Code-options: Specifies one or more Licensed Internal Code compile-time options. Changing the Licensed Internal Code options of an Integrated Language Environment (ILE) program causes the system to re-create the ILE program with the specified Licensed Internal Code options for all the bound modules. Note: Additional information about the LICOPT options can be found in the ILE Concepts book.

*NONE: Program recreation is forced and no Licensed Internal Code options are used for all the bound modules.

Note: The Change Program (CHGPGM) command must re-create the program to change the Licensed Internal Code options. To be eligible for re-creation, OPM programs must be observable and ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

FRCCRT
Specifies whether program re-creation is forced. OPM programs cannot be re-created unless they are observable. ILE programs must have all creation data. Use the Display Program (DSPPGM) command to determine whether a program is observable or has all creation data.

*NO: Program re-creation is not forced unless the optimization (OPTIMIZE), use adopted authority (USEADPAUT), user profile (USRPRF), enable performance collection (ENBPFRCOL), profiling data (PRFDTA), or Licensed Internal Code options (LICOPT), or enable teraspace storage (TERASPACE), parameters are changed. This option allows the system to determine whether a change is required.

*YES: Program re-creation is forced whether or not the optimization (OPTIMIZE), use adopted authority (USEADPAUT), user profile (USRPRF), enable performance collection (ENBPFRCOL), profiling data (PFRDTA), or Licensed Internal Code options (LICOPT), or enable teraspace storage (TERASPACE), parameters are changed.

*NOCRT: No program re-creation is done. If a value other than *SAME is specified for OPTIMIZE, USEADPAUT, USRPRF, ENBPFRCOL, PRFDTA, LICOPT, or TERASPACE parameter, a command syntax error is sent and the command is not run.

TEXT
Specifies the text that briefly describes the program. More information is in Commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CHGPGM

Example 1: Optimizing a Program 

CHGPGM   PGM(PROG1/SERVICE)  OPTIMIZE(*YES)
  USRPRF(*OWNER)

The program SERVICE in library PROG1 is optimized, and the user profile under which it is processed is changed to include the program owner's user profile. Only the owner of program PROG1/SERVICE, or a user with security officer authority, can change the USRPRF attribute. The program is re-created only if the attributes specified differ from those of the current program.

Example 2: Changing Text for a Program 

CHGPGM   PGM(*USRLIBL/KNUTE)
  TEXT('Program description')

This command changes the text for program KNUTE. The user portion of the library list is used to find the program.

Example 3: Optimizing Multiple Programs 

CHGPGM   PGM(PROG1/ACE*)  OPTIMIZE(*YES)

All programs in library PROG1 whose names begin with ACE, are optimized to their maximum optimization level.

Example 4: Changing Text of Multiple Programs 

CHGPGM   PGM(PROG2/*ALL)  TEXT('Generic Text')

This command changes the text of all programs in library PROG2 to Generic Text.

Example 5: Enabling collection of profiling data 

CHGPGM   PGM(PROG1/PROFPGM)  PRFDTA(*COL)

This command enables the collection of profiling data for program PROFPGM in library PROG1. If PROFPGM in library PROG1 had profiling data applied prior to issuing this command, all applied profiling data will be removed.

Example 6: Applying profiling data 

CHGPGM   PGM(PROG1/PROFPGM)  PRFDTA(*APYALL)

This command applies block order and procedure order profiling data to program PROFPGM in library PROG1. The collection of profiling data is no longer enabled for program PROFPGM in library PROG1.

Error messages for CHGPGM

*ESCAPE Messages

CPF0540
*USRLIBL not allowed with generic name or *ALL.
CPF0541
Program &1 in &2 not changed.
CPF0542
Program &1 in library &2 not changed.
CPF0543
User &3 not authorized to change &1.
CPF0544
Programs in libraries QSYS and QGDDM cannot be changed.
CPF0545
No programs changed.
CPF0546
&1 changed. &2 did not require change. &3 not changed.
CPF0547
Cannot remove observable information.
CPF0549
User &3 not authorized to change &1.
CPF223C
Not authorized to change the use adopted authority (USEADPAUT) attribute for &1 in &2 type *&3.
CPF223E
Authority check for use adopted authority attribute failed.
CPF9803
Cannot allocate object &2 in library &3.
CPF9804
Object &2 in library &3 damaged.
CPF9806
Cannot perform function for object &2 in library &3.
CPF9810
Library &1 not found.
CPF9811
Program &1 in library &2 not found.
CPF9818
Object &2 in library &3 not created.
CPF9819
Object &2 in library &3 not created.
CPF9820
Not authorized to use library &1.
CPF9821
Not authorized to program &1 in library &2.
CPF9830
Cannot assign library &1.