UPDSRVPGM (Update Service Program)

UPDSRVPGM Command syntax diagram

 

Purpose

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

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

 

Restrictions

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

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

  3. You must be the owner, a member of a group who is the owner of the bound service 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

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

The name of the bound service 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 service program is located.

service-program-name: Specify the name of the bound service 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 service program.

*NONE: No modules are specified.

Note: Specifying *NONE for this parameter allows updating of other service program attributes. The existing modules(s) in the service program are used with the other parameters specified on the UPDSRVPGM command.

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 service program.

module-name: Specify the name of the module that replaces a module of the bound service 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 service program contains only one module of the specified name and it is replaced. If two or more modules of the bound service program have the specified name, an exception is signaled and the bound service program is not updated.

*FIRST: The first module of the specified name in the module list of the bound service 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.

EXPORT
Specifies the variables and procedures that are to be exported from the updated service program. This parameter also specifies whether new signatures identifying the sequence of exports in the service program are created.

*CURRENT: The variables, procedures, and signatures currently exported from the service program continue to be exported. No new signatures are created.

Note: If a variable or procedure that is currently exported is not available for export after the update, an exception is signaled and the service program is not updated.

*SRCFILE: The variables and procedures of the source file and source member specified on the SRCFILE and SRCMBR parameters are exported. If the specified source file differs from the one used to create the service program, a new signature or set of signatures may be created.

Note: If a signature is lost, some current clients of the service program may not be able to use the service program without binding again.

*ALL: All variables and procedures exported from the modules of the service program are exported from the updated service program.

If the number or names of the variables and procedures exported before the service program update differs from those exported after the service program update, a new signature is created.

Note: If a new signature is created, all clients of the service program must be bound again before they can use the service program.

SRCFILE
Specifies the source file containing the specifications for exporting variables and procedures from this bound service program.

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

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

QSRVSRC: The default source file containing the specifications for exporting variables and procedures is used.

source-file-name: Specify the name of the source file containing the specifications for exporting variables and procedures.

SRCMBR
Specifies the name of the member in the source file specified on the SRCFILE parameter that contains the specifications for exporting variables and procedures from this bound service program.

*SRVPGM: The source file member has the same name as the service program being updated.

source-file-member-name: Specify the name of the member that contains the specifications for exporting.

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 service program. If the specified service program can resolve external symbols, it is added to the service programs that are bound to the bound service program.

*NONE: No service programs, except those in the bound service program being updated, 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 service 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 service 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 service 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 service program.

*NONE: No binding directories, except those in the bound service program being updated, are examined during symbol resolution.

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 service program was given *CALLER activation group at the time it was created.

activation-group-name: The name of the activation group that is associated with this called service program. If the service 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 service program object is updated.

Program Creation Options

*GEN: An updated service program object is created.

*NOGEN: An updated service 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 modules 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 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 service program being updated. This module was originally bound into the bound service program from a binding directory to resolve one or more imports. Imports are not resolved for this service program update.

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

Note: Bound service programs may grow significantly over time when *NOTRIM is specified.

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

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

Resolving References Options

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

*UNRSLVREF: All imports do not need to resolve to exports for the bound service 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 UPDSRVPGM 

UPDSRVPGM   SRVPGM(WORKDOC)  MODULE(BIN/TASKTWO)
  RPLLIB(*MODULE)

This command replaces the module named TASKTWO in the service program object named WORKDOC with another module named TASKTWO in the library BIN, only if the module being replaced was originally from the library BIN.

Error messages for UPDSRVPGM

*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.
CPF5CE1
Service program &1 not updated.
CPF5CE2
Unexpected error occurred during program or service program update.
CPF5D1C
Update of service program &1 in library &2 not allowed.