Update Service Program (UPDSRVPGM)

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 using the version of the service program in the QRPLOBJ library

Restrictions:

You must have use (*USE) and add (*ADD) authorities to the library of the service program.
You must have *USE, object management (*OBJMGT), and object existence (*OBJEXIST) authorities to the service program.
You must be the owner of the service program, or a member of a group who is the owner of the service program, or be a user with all object (*ALLOBJ) special authority.
You must have *USE authority to the following:
- *MODULE objects specified on the Module (MODULE) parameter, and execute (*EXECUTE) authority to the library that the module resides in.
- *SRVPGM objects specified on the Bind service program (BNDSRVPGM) parameter.
- *BNDDIR objects specified on the Binding directory (BNDDIR) parameter, and *EXECUTE authority to the library, and all objects used to resolve external symbols for these *BNDDIR objects, and their libraries.
- Object operational (*OBJOPR) and read (*READ) authorities to the file specified for the Export source file (SRCFILE) parameter.

Parameters

Keyword	Description	Choices	Notes
SRVPGM	Service program	Qualified object name	Required, Positional 1
	Qualifier 1: Service program	Name
	Qualifier 2: Library	Name, USRLIBL, CURLIB
MODULE	Module	Single values: NONE Other values (up to 300 repetitions): Qualified object name*	Required, Positional 2
	Qualifier 1: Module	Generic name, name, *ALL
	Qualifier 2: Library	Name, LIBL, CURLIB, *USRLIBL
EXPORT	Export	CURRENT, SRCFILE, *ALL	Optional
SRCFILE	Export source file	Qualified object name	Optional
	Qualifier 1: Export source file	Name, QSRVSRC
	Qualifier 2: Library	Name, LIBL, CURLIB
SRCMBR	Export source member	Name, *SRVPGM	Optional
RPLLIB	Replacement library	Single values: ONLY, FIRST, MODULE Other values: Qualifier list*	Optional
RPLLIB	Qualifier 1: Replacement library	Name	Optional
BNDSRVPGM	Bind service program	Single values: NONE Other values (up to 300 repetitions): Qualified object name*	Optional
	Qualifier 1: Bind service program	Generic name, name, *ALL
	Qualifier 2: Library	Name, *LIBL
SRVPGMLIB	Bound *SRVPGM library name	Single values: SAME, LIBL Other values: Qualifier list	Optional
SRVPGMLIB	Qualifier 1: Bound *SRVPGM library name	Name	Optional
BNDDIR	Binding directory	Single values: NONE Other values (up to 300 repetitions): Qualified object name*	Optional
	Qualifier 1: Binding directory	Name
	Qualifier 2: Library	Name, LIBL, CURLIB, *USRLIBL
ACTGRP	Activation group	Name, *SAME	Optional
OPTION	Creation options	Values (up to 6 repetitions): GEN, NOGEN, DUPPROC, NODUPPROC, DUPVAR, NODUPVAR, WARN, NOWARN, TRIM, NOTRIM, RSLVREF, UNRSLVREF	Optional
DETAIL	Listing detail	NONE, BASIC, EXTENDED, FULL	Optional

Top

Service program (SRVPGM)

Specifies the service program that is to be updated.

This is a required parameter.

Qualifier 1: Service program

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

Qualifier 2: Library

*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.
name: Specify the name of the library where the bound service program is located.

Module (MODULE)

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

If the library of the module being replaced is different from the library of the replacing module, the module's library after the update will remain the library the module was in when the service program was first created. If the RPLLIB parameter is required to determine which module to replace, the value to be entered in the RPLLIB parameter for this module will not change due to the update.

This is a required parameter.

Single values

*NONE: No modules are specified.
Note: This value can be specified when the module is not changing, but you are updating the service program (the BNDSRVPGM parameter) or the binding directory (BNDDIR parameter) to examine for exports. The existing module is used.

Qualifier 1: Module

*ALL: All modules of the same name to which the user has authority replace the modules of the bound service program.
generic-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.
name: Specify the name of the module that replaces a module of the bound service program.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread 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.
name: Specify the name of the library to be searched.

Export (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 source file member identified by the Source file (SRCFILE) and Source member (SRCMBR) parameters contains EXPORT statements that identify the data and procedures to export from the service program. 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.

Export source file (SRCFILE)

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

Qualifier 1: Export source file

QSRVSRC: The source file name is QSRVSRC.
name: Specify the name of the source file containing the specifications for exporting variables and procedures.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread 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.
name: Specify the name of the library to be searched.

Replacement library (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.
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.

Bind service program (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. Up to 300 names can be specified.

Single values

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

Qualifier 1: Bind service program

*ALL: All service programs are examined during symbol resolution.
generic-name: Specify the generic name of the service programs 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.
name: Specify the name of the service program to examine during symbol resolution.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

name: Specify the name of the library to be searched. QTEMP is not a valid library name for this parameter.

Bound *SRVPGM library name (SRVPGMLIB)

Specifies the library name used to resolve to currently bound service programs. A value other than *SAME for this parameter can be specified if the program attribute ALWLIBUPD is *YES.

*SAME: Use the library name where the service program (*SRVPGM) is currently bound from.
*LIBL: All libraries in the job's library list are searched until the first match is found for each bound *SRVPGM. The first occurrence of a *SRVPGM is 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 is 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) are not changed.
name: Specify 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 is 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 is used. You must have *USE authority to the *SRVPGM objects in the library specified and *EXECUTE authority to the library itself.

Binding directory (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. Up to 300 names can be specified.

Single values

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

Qualifier 1: Binding directory

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

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread 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.
name: Specify the name of the library to be searched.

Activation group (ACTGRP)

Specifies the activation group to be used for the updated service program.

*SAME: The activation group is not changed. Specify this value if the service program was given *CALLER activation group at the time it was created.
name: Specify 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: Changing the activation group name can affect the behavior of the program (or service program). Refer to the ILE Concepts book, SC41-5606 for detailed information on the behavior of named activation groups.

Creation options (OPTION)

Specifies the options to be used when the service program object is updated.

You can specify up to 6 values for this parameter.

Creating Program Objects

*GEN: An updated program object is created.
*NOGEN: An updated program object is not created.

Duplicate Procedure Names

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

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

Issuing Diagnostic Messages

*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

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: Bound service 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 during this program update, the exports that the modules contain are not available for other program updates.

Resolving References (Imports)

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

Listing detail (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).