Move Library to ASP (QHSMMOVL) API

Required Parameter Group:

1	Library name	Input	Char(10)
2	Target auxiliary storage pool (ASP) number	Input	Binary(4)
3	Check dependencies	Input	Char(10)
4	Error Code	I/O	Char(*)

Optional Parameter Group 1:

5	Target auxiliary storage pool (ASP) device name	Input	Char(10)
6	Source auxiliary storage pool (ASP) number	Input	Binary(4)
7	Source auxiliary storage pool (ASP) device name	Input	Char(10)

Default Public Authority: *USE

Threadsafe: No

The Move Library to ASP (QHSMMOVL) API moves a library and its contents from its existing auxiliary storage pool (ASP) to the specified target ASP through a save and restore operation. The API preserves private authorities to the objects that would normally be lost with a save and restore operation.

Program (*PGM) objects in the library will be placed in library QRPLOBJ (or library QRPLxxxxx if the library is in a primary or secondary ASP (where 'xxxxx' is the ASP number of the primary ASP of the ASP group)) and a copy of each *PGM object will be moved with the library to the target ASP.

After a library has been moved, the following attributes are changed for every object in the library and the library.

The date last used will be set to blank.
The change date and time will be set to the current date and time.
The days used count will be set to zero.
The date use count reset will be set to blank.
The restore date and time will be set to the current date and time.

Restrictions

Data queue entries are not moved and will be lost.
The QSYSWRK subsystem must be active.
A library cannot be moved in the following cases:
- The library is considered a system library. The restricted libraries are:
  - Any library with a name that begins with the letter 'Q'.
  - Any library with a name that begins with the symbol '#' that is not considered a user library and the target ASP is not a basic user ASP.
  - Libraries SYSIBM, SYSIBMADM, SYSPROC, and SYSTOOLS.
  - Library SYSIBxxxxx (where xxxxx is the number of a primary ASP).
- The library cannot be renamed. See the Rename Object (RNMOBJ) command for the restrictions on renaming a library.
- The library contains *JRN or *JRNRCV objects, objects that are journaled or the library itself is journaled.
- The library contains files with database dependencies outside the library.
- The library is in the library list of the current thread.
- The library is in the library list of any primary thread that is active on the system when the QLIBLCKLVL system value is set to lock libraries in the library list.
- The library contains an allocated job queue or output queue.
- The target ASP does not have enough space for the library and its objects.
- The target ASP is not either the system ASP (ASP 1), a basic user ASP (ASPs 2-32), or a primary or secondary ASP in the range of 33-255. A library object (*LIB) must be able to be created into the target ASP, which means that the ASP cannot be a UDFS ASP and it cannot contain a journal, journal receiver or save file object where the object's ASP is a basic user ASP and the object's library is in the system ASP.
- When the target ASP is a primary or secondary ASP, the library contains a job queue object (*JOBQ).
- When the target ASP is a primary or secondary ASP, the library must contain only object types that can reside in an ASP. For a list of supported and unsupported object types in a primary or secondary ASP, see Independent disk pool examples.

Authorities and Locks

Auxiliary Storage Pool (ASP) Device Authority: *USE authority for each auxiliary storage pool (ASP) device in the ASP group when a specific ASP device name is specified for the source or target auxiliary storage pool (ASP) device name or when a value greater than 32 is specified for the source or target auxiliary storage pool (ASP) number.
Object Authority: See Authority required for objects used by commands in the Security reference topic collection for detailed information about object authorities required when you save objects.
Library Authority: *OBJALTER
Object Lock: See the Backing up your system topic collection for detailed information about locks that are applied to objects during save operations.
Library Lock: *EXCL; To prevent access to other jobs, the library is renamed to QHSMLIBxxx where xxx is a numeric increment to allow multiple concurrent move operations.

Required Parameter Group

Library name

INPUT; CHAR(10)

The name of the library to be moved to the specified auxiliary storage pool (ASP).

Target auxiliary storage pool (ASP) number

INPUT; BINARY(4)

The number of the auxiliary storage pool (ASP) to which the library is to be moved. The following values can be used for the ASP number:

1-255	The number that was assigned to the ASP at creation time. ASP 1 is the system ASP. ASP numbers 2-32 are basic user ASPs. ASPs specified in the range of 33-255 must be either primary or secondary ASPs and have a status of 'Available'. This ASP must be different from the ASP where the library exists.
-1	The ASP value is determined from the target auxiliary storage pool (ASP) device name parameter.

Check dependencies

INPUT; CHAR(10)

Identifies whether object and journal dependencies should be checked and whether the API is to return after the dependency checking. When object dependencies are checked, the API validates that every object type in the library can exist in the target ASP. When journal dependencies are checked, the API validates that there are no *JRN or *JRNRCV objects, no journaled objects in the library and the library itself is not journaled. Database dependencies are always checked to validate that there are no database dependencies outside the library. You can use one of the following values:

*YES	The API will check for object dependencies, database dependencies outside the library, and for journal dependencies. An exception is signaled in case any of the conditions are found.
*NO	The API bypasses the validation for object and journal dependencies. The database dependencies outside of the library are checked. This value could be used to save on processing time if the user knows that dependencies do not exist. However, the API will end abnormally during the move operation if dependency conditions are encountered.
*VALIDATE	The same validation is done as when "*YES" is specified. The library is not moved to the target ASP. Completion message CPCB79F will be sent to the caller of the API indicating that the library can be moved to the selected ASP. This option is best used for planning purposes to determine which libraries can be moved to a specific ASP.

Error code

I/O; CHAR(*)

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

Optional Parameter Group 1

Target auxiliary storage pool (ASP) device name

INPUT; CHAR(10)

The name of the auxiliary storage pool (ASP) device from which storage is allocated for the library after the move. The ASP device must have a status of 'Available'. If this parameter is omitted, the target auxiliary storage pool (ASP) number parameter will be used. This parameter must be *TGTASP if specified when the target auxiliary storage pool (ASP) number parameter has a value other than -1. The target ASP device must be different from the ASP device where the library currently exists.

One of the following special values may be specified:

*TGTASP	The ASP is determined from the target auxiliary storage pool (ASP) number parameter.
*CURGRPPRI	If the current thread has an ASP group, the storage for the library is allocated from the the primary ASP of the group.
*SYSTEM	The system ASP (ASP 1).

Source auxiliary storage pool (ASP) number

INPUT; BINARY(4)

The number of the auxiliary storage pool (ASP) from which the library is to be moved. If this parameter and the source auxiliary storage pool (ASP) device name parameter are both omitted, the library name space for the current thread will be searched for the library.

The following values for the ASP number can be used:

1-255	The number that was assigned to the ASP at creation time. ASP 1 is the system ASP. ASP numbers 2-32 are basic user ASPs. ASPs specified in the range of 33-255 must be either primary or secondary ASPs and have a status of 'Available'.
-1	The ASP value is determined from the source auxiliary storage pool (ASP) device name parameter.

Source auxiliary storage pool (ASP) device name

INPUT; CHAR(10)

The name of the auxiliary storage pool (ASP) device from which storage is allocated for the library to be moved. The ASP device must have a status of 'Available'. This parameter must be *ASP if specified when the source auxiliary storage pool (ASP) number parameter has a value other than -1. If this parameter and the source auxiliary storage pool (ASP) number parameter are both omitted, the library name space for the current thread will be searched for the library.

One of the following special values may be specified:

*ASP	The ASP to be searched is determined from the source auxiliary storage pool (ASP) number parameter.
*	The ASPs in the library name space for the current thread will be searched for the library.
*CURASPGRP	The ASPs in the ASP group for the current thread will be searched for the library.
*SYSBAS	The system ASP (ASP 1) and defined basic user ASPs (ASPs 2-32) will be searched for the library.

Error Messages

Message ID	Error Message Text
CPFB78A E	Job queue &1 in library &2 is attached to subsystem &3.
CPFB78C E	Library &1 not moved or migrated.
CPFB78D E	Library &1 not moved or migrated.
CPFB78E E	Move or migrate of library &1 failed.
CPFB78F E	Move or migrate of library &1 failed
CPFB780 E	Not authorized to library &1.
CPFB782 E	Library &1 cannot be moved or migrated into an object-based ASP &2.
CPFB784 E	Target ASP &1 is not valid for the move or migrate operation.
CPFB785 E	Library &1 contains objects not valid for selected ASP.
CPFB786 E	Insufficient disk capacity in ASP &1 for specified objects.
CPFB787 E	Library &1 has journal dependencies.
CPFB788 E	Library &1 has database dependencies.
CPFB789 E	Output queue &1 in library &2 is attached to writer &3.
CPFB79E E	Auxiliary storage pool &1 does not exist.
CPFB791 E	Cannot access object &1 in library &2 type &3.
CPFB792 E	An error was encountered while moving or migrating library &1.
CPFB793 E	Move or migrate of job queue entries failed.
CPFB794 E	Move of output queue entries failed.
CPFB795 E	Library &1 cannot be allocated.
CPFB799 E	Unexpected condition with &1 API. Reason &6.
CPFB8ED E	Device description &1 not correct for operation.
CPF2115 E	Object &1 in &2 type *&3 damaged.
CPF2166 E	Library name &1 not valid.
CPF218C E	&1 not a primary or secondary ASP.
CPF24B4 E	Severe error while addressing parameter list.
CPF3C36 E	Number of parameters, &1, entered for this API was not valid.
CPF3C3C E	Value for parameter &1 not valid.
CPF3C90 E	Literal value cannot be changed.
CPF9810 E	Library &1 not found.
CPF9814 E	Device &1 not found.
CPF9825 E	Not authorized to device &1.
CPF9833 E	CURASPGRP or CURGRPPRI specified and thread has no ASP group.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V4R3

[ Back to top | Object APIs | APIs by category ]