UPDPGM (Update Program)

UPDPGM Command syntax diagram

 

Purpose

The Update Program (UPDPGM) command can be used to replace modules of an Integrated Language Environment (ILE) bound program with other modules on the system, without requiring you to change or recompile the bound program. Modules being replaced must be module objects (*MODULE) on the system.

Other jobs running the bound program can run while the program is being updated with this command. The currently running bound program is moved to library QRPLOBJ and an updated version of the bound program is inserted into the library of the bound program. Current activations of the program will continue running with the QRPLOBJ version.

 

Restrictions

  1. You must have *CHANGE authority to the library of the bound program.

  2. You must have *USE, *OBJMGT, and *OBJEXIST authorities to the bound program.

  3. You must be the owner, a member of a group who is the owner of the bound program, or be a user with *ALLOBJ authority.

  4. You must have *USE authority to the following:

    • *MODULE objects specified on the MODULE parameter, and their libraries.

    • *SRVPGM objects specified on the BNDSRVPGM parameter, and their libraries.

    • *BNDDIR objects specified on the BNDDIR parameter, and their libraries, and all objects used to resolve external symbols for these *BNDDIR objects, and their libraries.

 

Required Parameters

PGM
Specifies the name of the bound program that is to be updated.

The name of the bound 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.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the bound program is located.

program-name: Specify the name of the bound program that is to be updated.

MODULE
Specifies the names of the existing *MODULE objects that are to replace the modules of the same name in the bound program. If two or more modules of the bound program have the same name, the RPLLIB parameter indicates which is to be replaced.

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

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*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 modules of the same name, to which the user has authority, replace the modules of the bound program.

*NONE: No modules are specified.

generic*-module-name: Specify the generic name of the modules that replace the modules of the bound program. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. All modules with names that begin with the generic name, and for which the user has authority, replace the modules of the bound program.

module-name: Specify the name of the module that replaces a module of the bound program.

 

Optional Parameters

RPLLIB
Specifies the method used to select the module to be replaced when two or more modules of the bound program have the name specified on the MODULE parameter.

*ONLY: The bound program contains only one module of the specified name and it is replaced. If two or more modules of the bound program have the specified name, an exception is signaled and the bound program is not updated.

*FIRST: The first module of the specified name in the module list of the bound program is replaced.

*MODULE: The module that originated from the same library as the specified module is replaced. If no module of the specified name originally came from the same library as the replacing module, no module is replaced and an exception is signaled.

library-name: Specify the name of the originating library of the module to be selected for replacement. If no module of the specified name originated in the specified library, no module is replaced.

BNDSRVPGM
Specifies the service program to examine for exports if import requests to resolve external symbols cannot be met by the modules and service programs of the updated bound program. If the specified service program can resolve external symbols, it is added to the service programs that are bound to the bound program.

*NONE: No service programs are examined during symbol resolution.

The specified service program can be qualified by one of the following values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

library-name: Specify the name of the library to be searched. You cannot specify QTEMP for a library name.

*ALL: All service programs are examined during symbol resolution.

generic*-service-program-name: Specify the generic name of the service program to examine during symbol resolution. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. All service programs with names that begin with the generic name, and for which the user has authority, are examined during symbol resolution.

service-program-name: Specify the name of the service program to examine during symbol resolution.

SRVPGMLIB
Library name to use to resolve to currently bound service programs. A value other than *SAME for this parameter may be specified if the program attribute ALWLIBUPD is *YES.

The possible library values are:

*SAME: Use the library name where the service program (*SRVPGM) is currently bound from.

*LIBL: All libraries in the job's library list will be searched until the first match is found for each bound *SRVPGM. The first occurrence of a *SRVPGM will be used to resolve to currently bound service programs and *LIBL is saved to be used at run time. If no match is found in the job's library list, the *SRVPGM currently bound to the program will be used. You must have *USE authority to the *SRVPGM objects in the library specified and *EXECUTE authority to the library itself. Note the service programs that came from the implicit binding directories (system-supplied service programs) will not be changed.

library-name: The name of the library to be used first to resolve to all currently bound service programs. If a bound *SRVPGM does exist in the library specified on SRVPGMLIB parameter, that *SRVPGM from that library will be used instead of the currently bound *SRVPGM and the library name specified on the SRVPGMLIB parameter is saved to be used at run time. If a *SRVPGM does not exist in the library specified on the SRVPGMLIB parameter, the *SRVPGM currently bound to the program will be used. You must have *USE authority to the *SRVPGM objects in the library specified and *EXECUTE authority to the library itself. Note the service programs that came from the implicit binding directories (system supplied service programs) will not be changed. You cannot specify QTEMP for a library name.

BNDDIR
Specifies the binding directory to examine for exports if import requests to resolve external symbols cannot be met by (1) the modules and service programs of the updated bound program or by (2) the service program specified on the BNDSRVPGM parameter. If a module or service program listed in the specified binding directory can resolve external symbols, it is added to the modules or service programs that are bound to the bound program.

*NONE: No binding directories are specified.

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

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

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

binding-directory-name: Specify the name of the binding directory to be used during symbol resolution.

ACTGRP
Activation group name.

The possible values are:

*SAME: The activation group will not be changed. Specify this value if the program was given *CALLER or *NEW activation group at the time it was created.

activation-group-name: The name of the activation group that is associated with this called program. If the program was given a named activation group at the time it was created, the name of that activation group can be changed to another named activation group. Note that changing the activation group name can affect the behavior of the program (or service program)". Please refer to the ILE Concepts book for detailed information on the behavior of named activation groups.

OPTION
Specifies the options to be used when the bound program is updated.

Program Creation Objects

*GEN: An updated program object is created.

*NOGEN: An updated program object is not created.

Duplicate Procedure Name Options

*DUPPROC: During symbol resolution, the procedures that are exported from the modules and service programs need not be unique. The first procedure of the specified module and service programs that matches the import request is exported.

*NODUPPROC: During symbol resolution, each procedure that is exported from the modules and service programs must be unique.

Duplicate Variable Name Options

*DUPVAR: During symbol resolution, the variables that are exported from the modules and service programs need not be unique. The first variable of the specified modules and service programs that matches the import request is exported.

*NODUPVAR: During symbol resolution, each variable that is exported from the modules and service programs must be unique.

Diagnostic Message Options

*WARN: The appropriate diagnostic messages are signaled. Also, if you specify duplicate procedures or variables (*DUPPROC or *DUPVAR) and duplicates are found, a diagnostic message is issued indicating what duplicates were found.

*NOWARN: No information or diagnostic messages are issued.

Trimming Marooned Modules Options

A marooned module is a module of the bound program being updated. This module was originally bound into the bound program from a binding directory to resolve one or more imports. Imports are not resolved for this program update.

*NOTRIM: Marooned modules are not removed from the bound program.

Note: Programs may grow significantly over time when *NOTRIM is specified.

*TRIM: Marooned modules are removed from the bound program.

Note: If marooned modules are removed from the bound program for this program update, the exports that the modules contain are not available for other program updates. System objects referred to by the removed module are not removed (see the DSPPGMREF command).

Resolving References Options

*RSLVREF: All imports must be resolved to exports for the bound program to be updated.

*UNRSLVREF: All imports do not need to resolve to exports for the bound program to be updated.

Note: If this command contains an import that does not resolve, an exception will be generated when the command is run.

DETAIL
Specifies the level of detail of the binder listing to be printed. The printer file *LIBL/QSYSPRT is used to create the listing.

*NONE: No binder listing is printed.

*BASIC: The brief summary table, the options passed to this command, and some processing statistics are printed.

*EXTENDED: The extended summary table and the binding information listing are printed, in addition to the information provided in the *BASIC listing (the brief summary table, the options passed to this command, and some processing statistics).

*FULL: The Cross-reference listing is printed, in addition to the information provided in the *EXTENDED listing (the extended summary table, the binding information listing, the brief summary table, the options passed to this command, and some processing statistics).

Example for UPDPGM 

UPDPGM   PGM(STAR)  MODULE(SKY/NOVA)  RPLLIB(*FIRST)

This command replaces the first module named NOVA existing in the program object STAR with the module NOVA in the library SKY.

Error messages for UPDPGM

*ESCAPE Messages

CPF223D
Not authorized to update &1 in &2 type *&3.
CPF223E
Authority check for use adopted authority attribute failed.
CPF5CA7
SRVPGMLIB must be *SAME when ALWLIBUPD is *NO.
CPF5CE0
Program &1 not updated.
CPF5CE2
Unexpected error occurred during program or service program update.
CPF5D1B
Update of program &1 in library &2 not allowed.