Allocate Licensed Internal Code (LIC) Space (QLPALCSP) API

Required Parameter Group:

1	Allocate space for release	Input	Char(10)
2	Start space allocation	Input	Char(1)

Optional Parameter Group:

3	IPL required	Output	Char(1)
4	Error code	I/O	Char(*)

Default Public Authority: *EXCLUDE

Threadsafe: No

This API should be used prior to upgrading to the next release of the operating system to have licensed internal code (LIC) allocate any additional LIC space required for that release. The space will be be allocated during the next IPL. To save IPL time, the process to free space that will be allocated during IPL can be started immediately.

Note: Once the additional LIC space has been allocated, the space cannot be returned to the user. This API can be used to toggle on and off the action for LIC to allocate this space during the next IPL as many times as necessary prior to performing the IPL.

To determine whether the release being installed requires any additional space, see the IBM^® i Information Center for information about allocating additional LIC space and for preparation tasks for upgrading or replacing software.

Authorities and Locks

You are required to have system configuration (*IOSYSCFG) special authority to use this API.

Required Parameter Group

Allocate space for release

INPUT; CHAR(10)

Indicates whether or not additional space should be allocated, and if it should be allocated, the release of the operating system that needs the additional space.

The valid values are:

*NONE: No additional space should be allocated for LIC at this time or during the next IPL for any release. If space was already being freed, that action will be stopped. If the space was already allocated during an IPL, it cannot be undone. Any space freed during a previous call to this API will be returned to the user.
VxRyMz: The version, release, and modification level of the operating system that will be installed. The release must be in the format VxRyMz. Valid values for x and y are 0 through 9. Valid values for z are 0 through 9 or A through Z. For example, V5R4M0 is version 5, release 4, modification 0.

Start space allocation

INPUT; CHAR(1)

Determines whether the space will be allocated during the next IPL or if some of the space should be freed in a background task with the allocation process being completed during the next IPL. This parameter must be '0' when *NONE is specified for the Allocate space for release parameter.

Not all of the additional LIC space can be freed while the system is operational. The rest of the space will be freed during the next IPL.

The valid values are:

0: Licensed Internal Code is to allocate all of the additional space required for the specified release during the next IPL. This value will also cause LIC to stop freeing space due to a previous call to QLPALCSP with the Start space allocation parameter set to '1'.
1: Licensed Internal Code is to begin freeing space for the specified release immediately. The space can be allocated more quickly during the next IPL as LIC does not need to free that space during the IPL process. This option is recommended to minimize the length of time the next IPL will take to complete the operation.

Note: Regardless of whether a '0' or '1' was specified for the Start space allocation parameter, an IPL will be required if the IPL required parameter returns a value of '1'.

Optional Parameter Group

IPL required

OUTPUT; CHAR(1)

This parameter will let you know whether or not an IPL is needed to allocate the additional LIC space. If the release you are currently using already has sufficient space needed to upgrade, there will be no need to perform an IPL. If an IPL is not necessary and if this parameter is not specified, informational message CPI3DBF (Allocating additional space is not necessary) will be sent to the joblog.

0: An IPL is not required. Sufficient LIC space exists for the specified release.
1: An IPL is required for LIC to allocate the additional required space. This IPL must occur prior to installing the specified release.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

The following messages may be sent from this function:

Message ID	Error Message Text
CPF222E E	&1. special authority is required.
CPF24B4 E	Severe error while addressing parameter list.
CPF3C36 E	Number of parameters, &1., entered for this API was not valid.
CPF3CF1 E	Error code parameter not valid.
CPF3DF7 E	Load source too small for &1.
CPF3DF8 E	Not enough free space on load source.
CPF3DF9 E	Allocate space for release value not valid
CPF3DFA E	Information not available for release &1.
CPF3DFB E	Start space allocation parameter not valid.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V5R4

[ Back to top | Software Product APIs | APIs by category ]