Restore Licensed Program (RSTLICPGM)

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

Restrictions:

This command is shipped with public *EXCLUDE authority.
To use this command, the user must have *SECADM and *ALLOBJ authority.
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.
If other objects of the licensed program are in use, they are not restored.
With the exception of overrides for the restore operation printing OUTPUT(*PRINT), this command ignores all file overrides currently in effect for the job.
Some licensed programs are restored only if the user is enrolled in the system distribution directory. See the publications for each licensed program for a description of this restriction.
This command does not restore code and language objects for the base operating system.
This command does not support the use of user ASPs (auxiliary storage pools). All objects supplied by a licensed program must remain in the system ASP.
At most one optical device, one save file, one virtual tape device or one tape media library device can be specified.

Parameters

Keyword	Description	Choices	Notes
LICPGM	Product	Character value	Required, Positional 1
DEV	Device	Single values: SAVF Other values (up to 4 repetitions): Name*	Required, Positional 2
OPTION	Optional part to be restored	*BASE, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 01, 02, 03, 04, 05, 06, 07, 08, 09	Optional
RSTOBJ	Type of object to be restored	ALL, PGM, *LNG	Optional
LNG	Language for licensed program	Character value, PRIMARY, SAVVOL	Optional
OUTPUT	Output	NONE, PRINT	Optional
RLS	Release	Character value, *FIRST	Optional
REPLACERLS	Replace release	Character value, ONLY, NO	Optional
VOL	Volume identifier	Single values: MOUNTED Other values (up to 75 repetitions): Character value*	Optional
SEQNBR	Sequence number	1-16777215, *SEARCH	Optional
ENDOPT	End of media option	REWIND, LEAVE, *UNLOAD	Optional
SAVF	Save file	Qualified object name	Optional
	Qualifier 1: Save file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
LIB	Library	Element list	Optional
	Element 1: Library 1	Name, *SAME
	Element 2: Library 2	Name, *SAME
	Element 3: Library 3	Name, *SAME
	Element 4: Library 4	Name, *SAME
	Element 5: Library 5	Name, *SAME
	Element 6: Library 6	Name, *SAME
	Element 7: Library 7	Name, *SAME
	Element 8: Library 8	Name, *SAME
	Element 9: Library 9	Name, *SAME
	Element 10: Library 10	Name, *SAME
	Element 11: Library 11	Name, *SAME
LNGLIB	Language library	Name, *SAME	Optional
FLR	Folder	Name, *SAME	Optional
CODHOMEDIR	Code home directory	Single values: PROMPT Other values (up to 300 repetitions): Path name, SAME	Optional
LNGHOMEDIR	Language home directory	Single values: PROMPT Other values (up to 300 repetitions): Path name, SAME	Optional
FRCOBJCVN	Force object conversion	Single values: SYSVAL, NO Other values: Element list	Optional
	Element 1: Convert during restore	*YES
	Element 2: Objects to convert	RQD, ALL

Top

Device (DEV)

Specifies the name of the device used for the restore of the licensed program. The device name must already be known on the system by a device description. Use the Work with Device Descriptions (WRKDEVD) command to display the names of the devices available on this system.

This is a required parameter.

The possible values are:

*SAVF: The restore operation is done using the save file name specified on the save file (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 tape media library device used for the restore operation.
tape-device-name: Specify the name of one or more tape devices to use to restore the licensed program. If a virtual tape device is used, it must be the only device specified. 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.

Type of object to be restored (RSTOBJ)

Specifies the type of licensed program objects to be restored.

The possible values are:

*ALL

All of the objects for the licensed program are restored. This includes both program objects and the language objects specified on the Language for licensed program prompt (LNG parameter).

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. *PGM should be used when restoring program objects from a distribution media where the program objects and selected language objects are not on the same distribution media or are not in consecutive order.

*LNG

Only the language objects for a licensed program are restored. The Language for licensed program prompt (LNG parameter) determines if the objects are associated with the licensed program library or with a multilingual library.

Language for licensed program (LNG)

Specifies the national language version (NLV) 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.

The possible values are:

*PRIMARY: The language feature of the operating system is restored for the specified licensed program.
Note: Use GO LICPGM 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. This option is not valid with DEV(*SAVF).
feature-codes: Specify the NLV identifier for the language file that is to be restored for the licensed program. More information on feature identifications and a list of IBM-supplied feature codes is in the Install, upgrade, or delete i5/OS and related software book, SC41-5120.

Replace release (REPLACERLS)

Specifies the version, release, and modification level of the licensed program being replaced.

The possible values are:

*ONLY: Replace only the version, release, and modification level of the licensed program currently installed.
*NO: The licensed program currently installed on the system is not replaced. The licensed program being restored must be a different release than the one currently installed. If the licensed program being restored exists in the same libraries as the installed program, an override parameter must be specified indicating to which libraries the licensed program 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.

Volume identifier (VOL)

Specifies the volume identifiers of the media or the cartridge identifiers of tapes in a tape media library device, from which the objects are being restored. The volumes must be in the same order as they were when the data was saved. The volume that contains the beginning of the file to be restored should be placed in the device.

The possible values are:

*MOUNTED: The licensed program is restored from the volumes that are currently on the device specified on the Device prompt (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.
Note: This value cannot be specified when using an optical media library device.
volume-identifier: Specify the identifiers of one or more volumes in the order they are put on the device and used to restore the licensed program. A maximum of 75 volume identifiers can be specified.

Sequence number (SEQNBR)

Specifies which sequence number to use for the restore process. This option is only valid for tape devices.

The possible values are:

*SEARCH: The volume that is placed in the device is searched for a data file with an identifier that matches the label for the specified licensed program or licensed program option. When a match is found, the objects are restored. If the last operation on the device specified *LEAVE on the End of media option prompt (ENDOPT parameter), indicating that the tape is positioned at the location where the last operation ended, the file search starts with the first data file beyond the current tape position. If *LEAVE was not used for the End of media option prompt (ENDOPT parameter) of the last operation, or if the tape was manually rewound since the operation, the search starts with the first data file on the volume.
file-sequence-number: Specify the sequence number of the file that is used for the restore process. Valid values range from 1 through 16777215.

End of media option (ENDOPT)

Specifies the operation that is automatically done on the tape or optical volume after the restore operation ends. If more than one volume is used, this parameter applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached.

Note: This parameter is valid only if a tape or optical device name is specified for 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 does not rewind or unload after the operation ends. It remains at the current position on the tape drive.

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

Save file (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 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.
library-name: Specify the name of the library where the save file exists.

The possible values are:

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

Code home directory (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.

The possible values are:

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

Language home directory (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.

The possible values are:

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

Force object conversion (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:

This parameter applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.
An object must have creation data (either observable or unobservable) to be converted.
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.

Single values

*SYSVAL: The objects are converted based on the value of the QFRCCVNRST system value.
*NO: The objects are not converted during the restore operation.
Note: If FRCOBJCVN(*NO) is specified, then the QFRCCVNRST system value must have a value of either "0" or "1".

Element 1: Convert during restore

*YES

The objects are converted during the restore operation.

Notes:

If FRCOBJCVN(*YES *RQD) is specified, then the QFRCCVNRST system value must have a value of "0", "1", or "2". FRCOBJCVN(*YES *RQD) will override a QFRCCVNRST value of "0" or "1". If FRCOBJCVN(*YES *ALL) is specfied, then QFRCCVNRST can have any valid value and FRCOBJCVN(*YES *ALL) overrides the QFRCCVNRST system value.
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 do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.
*ALL: All objects are converted regardless of their current format, including objects already in the current format. However, if the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.

Examples

Example 1: Restoring Program Using Defaults

RSTLICPGM   LICPGM(5722WDS)  DEV(TAP01)

This command restores the WebSphere Development Studio (5722WDS) 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(V5R2M0)
            REPLACERLS(*NO)  LIB(A B C)

This command restores the base part of the V5R2M0 1MYPROD product to the system if the base of the V5R2M0 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(5722WDS)  DEV(*SAVF)  SAVF(MYLIB/MYSAVF)

This command restores the WebSphere Development Studio (5722WDS) 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(V5R2M0)
            REPLACERLS(*NO)  LIB(A B C)  SAVF(MYLIB/MYSAVF)

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