RSTLICPGM (Restore Licensed Program)

RSTLICPGM Command syntax diagram

 

Purpose

The Restore Licensed Program (RSTLICPGM) command loads or restores a licensed program, either for initial installation or new-release installation.

 

Restrictions

  1. This command is shipped with public *EXCLUDE authority.

  2. To use this command, the user must have *SECADM and *ALLOBJ authority.

  3. If this command is used to restore a program in the licensed program, the copy of the program currently in the system should not be running while the program is being restored. If this occurs, the processing program is ended abnormally.

  4. If other objects of the licensed program are in use, they are not restored.

  5. With the exception of overrides for the restore operation printing OUTPUT(*PRINT), this command ignores all file overrides currently in effect for the job.

  6. Some licensed programs can only be restored if the user is enrolled in the system distribution directory. See the publication for each licensed program for a description of this restriction.

  7. This command does not restore code and language objects for the base OS/400 system.

  8. This command does not support the use of other ASPs (auxiliary storage pools). All objects supplied by a licensed program must remain in the system ASP.

 

Required Parameters

LICPGM
Specifies the 7-character identifier of the licensed program being restored. A list of IBM-supplied licensed programs is in the Software Installation Link to PDF book.

DEV
Specifies the name of the device from which the licensed program objects are restored. The device name must be known by a device description on the system. If multiple devices are specified, they must have compatible media formats.

Up to four device names can be specified. Use the Work with Device Descriptions (WRKDEVD) command to display the names of the tape devices available on this system. Only one save file name can be specified.

*SAVF: The restore operation is done using the save file name specified on the SAVF parameter.

optical-device-name: Specify the name of the optical device used for the restore operation.

tape-media-library-device-name: Specify the name of the media library device used for the restore operation.

tape-device-name: Specify the names of one or more tape devices used for the restore operation. If multiple tape devices are used, they must have compatible media formats and their names must be specified in the order in which they are used. Using more than one tape device permits one tape volume to be rewound and unloaded while another tape device processes the next tape volume.

 

Optional Parameters

VOL
Specifies the volume identifiers of the media volumes from which the licensed program is restored. The volumes must be installed on the device in the same order they were in when the licensed program was saved. The volume that contains the beginning of the file to be restored should be mounted on the device. A maximum of 75 entries can be specified.

*MOUNTED: The licensed program is restored from the volumes that are mounted on the device specified on the DEV parameter. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.

volume-identifier: Specify the identifiers of one or more volumes in the order they are mounted on the device and used to restore the licensed program.

OPTION
Specifies which licensed program option to restore.

*BASE: Only the base part of the licensed program is restored.

number-of-licensed-program-option: Specify the number associated with the optional part of the listed licensed program being restored.

RSTOBJ
Specifies the type of licensed program objects being restored.

*ALL: All objects of the licensed program are restored. This includes both the program objects and the language objects.

If a tape device is specified on the DEV parameter, then the RSTOBJ(*ALL) value is used when the saving of the licensed program has been done with the SAVLICPGM command such that the language objects immediately follow the program objects on the tape media. If the language objects (*LNG) and programming objects (*PGM) are not in consecutive order on the distribution tape, *ALL cannot be used in most cases. Instead, the program and language objects must be restored separately. The DSPTAP command can be used to determine the order of the objects on the tape. An example of how to restore language and program objects separately is in the "Examples" section at the end of this command.

If *SAVF is specified on the DEV parameter, then the RSTOBJ(*ALL) value can be used when the saving of the licensed program has been done with the SAVLICPGM command using OBJTYPE(*ALL).

*PGM: Only the program objects for the licensed program are restored. This value is used when restoring the program objects from the distribution media where the program objects and the selected language objects are not on the same distribution media or are not in consecutive order.

*LNG: The objects associated with the language identified by the language feature indicated on the LNG parameter are restored.

LNG
Specifies the language to be used for restoring the licensed program. If the language feature of the licensed program on the save media matches the system language feature, the language objects are restored to the licensed program's libraries. If the language features do not match, the language objects are restored into the multilingual library for that language feature.

*PRIMARY: The language feature of the operating system is restored for the specified product.

Note: Use the GO LICPGM function with option 20 to display the primary language of the operating system.

*SAVVOL: The language file on the mounted volume is to be restored for the licensed program specified by the user. This option is not valid with DEV(*SAVF).

feature-code: Specify the language feature identifier for the language file that is to be restored for the licensed program specified by the user. More information on feature identifications and a list of the IBM-supplied feature codes is in the Software Installation book.

SEQNBR
Specifies which sequence number to use for the restore operation.

*SEARCH: The volume on the device is searched for a data file for the licensed program; when a match is found, the objects are restored.

file-sequence-number: Specify the sequence number of the file. Valid values range from 1 through 16777215.

ENDOPT
Specifies the operation that is automatically performed on the tape or optical volume after the restore operation ends. If one or more volumes of tape is involved, this parameter applies only to the last volume.

Note: This parameter is valid only if a tape or optical device name is specified on the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.

*REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.

*LEAVE: The tape is not rewound. Another restore operation can start at the current position on the tape.

*UNLOAD: The tape is automatically rewound and unloaded after the restore operation has ended. Some optical devices will eject the volume after the operation ends.

SAVF
Specifies the qualified name of the save file containing the product.

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

save-file-name: Specify the name of the save file.

OUTPUT
Specifies whether a listing that shows information about the status of the object is created and directed to an output file. The listing shows the restore information and shows all objects, restored, not restored, and excluded. Information about each object's security is listed for the restored objects. More information on this parameter is in commonly used parameters.

*NONE: No output is created.

*PRINT: The output is printed with the job's spooled output.

RLS
Specifies the version, release, and modification level of the product being restored.

*FIRST: The first version, release, and modification level found on the distribution media is restored.

release-level: Specify the release level in VxRyMz format, where Vx is the version number, Ry is the release number, and Mz is the modification level. The variables x and y can be a number from 0 through 9, and the variable z can be a number from 0 through 9 or a letter from A through Z.

REPLACERLS
Specifies the version, release, and modification level of the product being replaced.

*ONLY: Replace only the version, release, and modification level of the product currently installed.

*NO: The product currently installed on the system is not replaced. The product being restored must be a different release than the product currently installed. If the product being restored exists in the same libraries as the installed product, then an override parameter must be specified indicating to which libraries the product is restored.

release-level: Specify the release level in VxRyMz format, where Vx is the version number, Ry is the release number, and Mz is the modification level. The variables x and y can be a number from 0 through 9, and the variable z can be a number from 0 through 9 or a letter from A through Z.

LIB
Specifies the libraries into which the product is being restored. This function is not supported by all products.

*SAME: The product is restored into the library specified by the vendor.

library-name: Specify the name of the library into which the product is being restored.

LNGLIB
Specifies the secondary language library into which the product is being restored. This function is not supported by all products.

*SAME: The product is restored into the secondary language library specified by the vendor.

library-name: Specify the name of the secondary language library into which the product is restored.

FLR
Specifies the name of the root folder into which the product is being restored. This function is not supported by all products.

*SAME: The root folder specified by the vendor is used.

folder-name: Specify the name of the root folder.

CODHOMEDIR
Specifies the directories into which the code part of the product is being restored. This function is not supported by all products.

Note: This parameter is mutually exclusive with the FLR parameter.

*SAME: The code part of the product is restored into the directories specified when packaged or already installed. *SAME may be specified as the only parameter value or within a list of directories. If used within a list, *SAME specifies that a particular directory is unchanged, though other directories may be different than when the product was packaged or previously installed.

*PROMPT: The code directories to be used are displayed. If the product is not currently installed, the directory names can be changed.

path-name: Specify the home path directory name into which the code part of the product is being restored. Up to 300 directories may be specified. For directory name entries which are unchanged, *SAME can be specified for the path name.

LNGHOMEDIR
Specifies the directories into which the language part of the product is being restored. This function is not supported by all products.

Note: This parameter is mutually exclusive with the FLR parameter.

*SAME: The language part of the product is restored into the directories specified when packaged or already installed. *SAME may be specified as the only parameter value or within a list of directories. If used within a list, *SAME specifies that a particular directory is unchanged, though other directories may be different than when the product was packaged or previously installed.

*PROMPT: The language directories to be used are displayed. If the product is not currently installed, the directory names can be changed.

path-name: Specify the home path directory name into which the language part of the product is being restored. Up to 300 directories may be specified. For directory name entries which are unchanged, *SAME can be specified for the path name.

FRCOBJCVN
Specifies whether to convert user objects to the format required for use in the current version of the operating system when the objects are restored.

 

Notes

  1. This parameter applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.

  2. An object must be observable (have the required observable information) in order to be converted.

  3. If an object needs to be converted (because it is formatted for an earlier version of the operating system), but is not converted during this restore operation, the object is automatically converted the first time it is used.

Element 1: Force Conversion

*SYSVAL: The objects are converted based on the value of the QFRCCVNRST system value.

Note: If this value is specified or defaulted and the system value QFRCCVNRST has a value of "1," the restore operation proceeds as if FRCOBJCVN(*YES *RQD) is specified.

*NO: The objects are not converted during the restore operation.

*YES: The objects are converted during the restore operation.

Note: Specifying this value increases the time of the restore operation, but avoids the need to convert the objects when they are first used.

Element 2: Objects to Convert

*RQD: The objects are converted only if they require conversion to be used by the current operating system. If the objects are not observable, the objects are restored but are not converted.

*ALL: All objects are converted regardless of their current format. Even if the objects are in the current format, they are converted again. However, if the objects are not observable, the objects are not restored.

Examples for RSTLICPGM

Example 1: Restoring Program Using Defaults 

RSTLICPGM   LICPGM(5716CD1)  DEV(TAP01)

This command restores the CoOperative Development Environment/400 (CODE/400) licensed program to the system. The tape containing the licensed program objects must be put on the TAP01 tape drive. Because no other parameters are specified, the defaults are used for the command.

Example 2: Restoring a Third Version of a Product 

RSTLICPGM   LICPGM(1MYPROD)  OPTION(*BASE)  DEV(TAP01)
  RLS(V3R6M0)  REPLACERLS(*NO)  LIB(A B C)

This command restores the base part of the V3R6M0 1MYPROD product to the system if the base of the V3R6M0 1MYPROD product is not currently installed on the system.

Example 3: Restoring One Version of a Product Over Another Version 

RSTLICPGM   LICPGM(2MYPROD)  OPTION(*BASE)  DEV(TAP01)
  RLS(*FIRST)  REPLACERLS(*ONLY)

This command restores the first version release modification level of the base part of the 2MYPROD product that is found on the tape in the TAP01 drive. It does not matter if the version release modification level of the base of the product on the tape matches the version release modification level of the base of the product on the system.

Example 4: Restoring Product From Save File 

RSTLICPGM   LICPGM(5716CD1)  DEV(*SAVF)
  SAVF(MYLIB/MYSAVF)

This command restores the CODE/400 licensed program to the system from the save file MYSAVF in MYLIB. Because no other parameters are specified, the defaults are used for the command.

Example 5: Restoring a Third Version of a Product From a Save File 

RSTLICPGM   LICPGM(1MYPROD)  OPTION(*BASE)  DEV(*SAVF)
  RLS(V3R6M0)  REPLACERLS(*NO)  LIB(A B C)
  SAVF(MYLIB/MYSAVF)

This command restores the base part of the V3R6M0 1MYPROD product to the system from save file MYSAVF in MYLIB if the base of the V3R6M0 1MYPROD product is not currently installed on the system.

Error messages for RSTLICPGM

*ESCAPE Messages

CPF3D94
No product found in save file.
CPF3D96
Objects for product &1 option &2 release &4 not restored.
CPF37A2
Licensed program &1 not valid.
CPF3728
Device &1 specified with other devices.
CPF3733
&2 &1 in &3 previously damaged.
CPF3739
Database file &1 member in &3 damaged.
CPF3820
&4 objects for &1 option &2 not restored.
CPF3880
No language objects exist.
CPF3884
Licensed program &1 option &2 not processed.
CPI36C9
Error occurred while removing PTFs.