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:

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 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.
7. This command does not restore code and language objects for the base operating system.
8. 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.
9. At most one optical device, one save file, one virtual tape device or one tape media library device can be specified.

Parameters

Product (LICPGM)

Specifies the seven-character identifier of the licensed program that is restored.

This is a required parameter.

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.

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

Optional part to be restored (OPTION)

Specifies which one of the optional parts of the licensed program given in the Product prompt (LICPGM parameter) is to be restored.

*BASE

Only the base part of the licensed program is to be restored.

number-of-licensed-program-option

Specify the number of the optional part of the listed licensed program that is to be restored.

Type of object to be restored (RSTOBJ)

Specifies the type of licensed program objects to be restored.

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

*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 Installing, upgrading, or deleting IBM i and related software book, SC41-5120.

Output (OUTPUT)

Specifies whether a listing that shows information about the status of the objects is created. The listing shows the parameter values that were specified and shows all objects, restored and not restored. Information about each object's security is listed for the restored objects.

*NONE

No output is created.

*PRINT

The output is printed with the job's spooled output.

Release (RLS)

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

*FIRST

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

release-level

The release-level can be passed as one of the following two formats:

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.

Specify the release-level in vvrrmm format, where vv are any numeric characters 00 through 35 representing the version of the product, rr are any numeric characters 00 through 35 representing the release of the product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the product. This format must be used if the version or release of the product is greater than 9.

Replace release (REPLACERLS)

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

*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

The release-level can be passed as one of the following two formats:

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.

Specify the release-level in vvrrmm format, where vv are any numeric characters 00 through 35 representing the version of the product, rr are any numeric characters 00 through 35 representing the release of the product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the product. This format must be used if the version or release of the product is greater than 9.

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.

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

*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 save file containing the product.

Qualifier 1: Save file

name

Specify the name of the save file.

Qualifier 2: Library

*LIBL

All libraries in the library list for the job are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the save file. If no current library entry exists in the library list, the QGPL library is used.

name

Specify the name of the library where the save file is located.

Library (LIB)

Specifies the libraries into which the licensed program is being restored. This function is not supported by all licensed programs.

*SAME

The licensed program is restored into the specified library.

library-name

Specify the name of the library into which the licensed program is being restored. A maximum of 11 libraries can be specified.

Language library (LNGLIB)

Specifies the secondary language library into which the secondary language objects are restored. This function is not supported by all licensed programs.

*SAME

The licensed program is restored into the specified secondary language library.

library-name

Specify the name of the secondary language library into which the licensed program is restored.

Folder (FLR)

Specifies the name of the root folder into which the licensed program is being restored. This function is not supported by all licensed program.

*SAME

Use the specified root folder.

folder-name

Specify the name of the root folder. The root folder is the folder on the system containing all of the other folders.

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.

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

*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, or to be compatible with the current machine, 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 have creation data (either observable or unobservable) to be converted.
3. If an object needs to be converted (because it is formatted for an earlier version of the operating system or is incompatible with the current machine), 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:

1. 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.
2. 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 or to be compatible with the current machine. 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 and machine compatibility, including compatible 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(5770WDS)  DEV(TAP01)

This command restores the Rational Development Studio (5770WDS) 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(5770WDS)  DEV(*SAVF)  SAVF(MYLIB/MYSAVF)

This command restores the Rational Development Studio (5770WDS) 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.

Error messages

*ESCAPE Messages

CPF3D96

Objects for product &1 option &2 release &6 not restored.