Update Service Program (UPDSRVPGM)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
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.
- You must have object operational (*OBJOPR) and read (*READ) authorities to the file specified for the Export source file (SRCFILE) parameter.
- You must have read (*R) authority to the stream file specified for the Export source stream file (SRCSTMF) parameter.
- You must have execute (*X) authority to each directory in the path of the stream file specified in the Export source stream file (SRCSTMF) parameter.
| Top |
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 |
| SRCSTMF | Export source stream file | Path name | Optional |
| RPLLIB | Replacement library | Single values: *ONLY, *FIRST, *MODULE Other values: Qualifier list |
Optional |
| Qualifier 1: Replacement library | Name | ||
| BNDSRVPGM | Bind service program | Single values: *NONE Other values (up to 300 repetitions): Element list |
Optional |
| Element 1: Service program | Qualified object name | ||
| Qualifier 1: Service program | Generic name, name, *ALL | ||
| Qualifier 2: Library | Name, *LIBL | ||
| Element 2: Activation | *SAME, *IMMED, *DEFER | ||
| SRVPGMLIB | Bound *SRVPGM library name | Single values: *SAME, *LIBL Other values: Qualifier list |
Optional |
| Qualifier 1: Bound *SRVPGM library name | Name | ||
| 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.
| Top |
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.
| Top |
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 Export source file (SRCFILE) and Export source member (SRCMBR) parameters or the Export source stream file (SRCSTMF) parameter 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.
| Top |
Export source file (SRCFILE)
Specifies the source file containing the specifications for the service program exports. This parameter cannot be specified with the Export source stream file (SRCSTMF) parameter.
Qualifier 1: Export source file
- QSRVSRC
- The source file name is QSRVSRC.
- name
- Specify the name of the source file containing the specifications for the service program exports.
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.
| Top |
Export source member (SRCMBR)
Specifies the member in the file specified for the Export source file (SRCFILE) parameter that contains the specifications for the service program exports. This parameter cannot be specified with the Export source stream file (SRCSTMF) parameter.
- *SRVPGM
- The source file member has the same name as the service program being updated.
- name
- Specify the name of the member that contains the specifications for exporting.
| Top |
Export source stream file (SRCSTMF)
Specifies the path name of the stream file containing the specifications for exporting data and procedures from this bound service program. This parameter can be an absolute path name or a relative path name. An absolute path name begins with a separator character (which is usually the / character). If the path name does not begin with a separator character, it is a relative path name and the system assumes the path starts with the current working directory of the job. The Export source stream file (SRCSTMF) parameter cannot be specified with the Export source file (SRCFILE) or Export source member (SRCMBR) parameters or if the object being updated has a target release earlier than V7R3M0.
- path-name
- Specify the path name of the stream file that contains the specifications for the service program exports.
| Top |
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.
| Top |
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. You can control the activation of each service program. You can specify whether the referenced service program is activated at the same time as the program or service program being created, or is deferred until a procedure exported from the referenced service program is called. Deferring activation may improve your application's performance.
Single values
- *NONE
- No service programs, except those in the bound service program being updated, are examined during symbol resolution.
Element 1: Service program
Qualifier 1: 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.
Element 2: Activation
- *SAME
- The referenced service program activation does not change.
- *IMMED
- Activation of the bound service program takes place immediately when the service program being updated is activated.
- *DEFER
- Activation of the bound service program may be deferred until a function it exports is called.
| Top |
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.
| Top |
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.
| Top |
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.
| Top |
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 procedure names that are exported from the modules and service programs need not be unique. Additional information may be found in the ILE Concepts book, SC41-5606.
- *NODUPPROC
- During symbol resolution, each procedure name that is exported from the modules and service programs must be unique.
Duplicate Variable Names
- *DUPVAR
- During symbol resolution, the variable names that are exported from the modules and service programs need not be unique. Additional information may be found in the ILE Concepts book, SC41-5606.
- *NODUPVAR
- During symbol resolution, each variable name 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.
| Top |
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).
| Top |
Examples
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.
| Top |
Error messages
*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.
- CPF5CAC
- The stream file could not be opened.
- 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.
| Top |