Package Installable Object (PKGINSOBJ)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Package Installable Object (PKGINSOBJ) command saves a copy of one or more objects of any file system and the associated name of the target library, folder or path where they must be created into an installable object. It also creates a distribution catalog entry and loads the installable object that contains the saved objects into the distribution repository.

Restrictions:

The GLBNAME consists of up to 9 tokens with the following format:
- At least 3 tokens should be specified.
- Only 1 token should contain the REF value and must be any token from the second to the eighth.
- A refresh level token must follow the REF token. This token must contain only characters from 0-9 and it must be the last token in the global name.
- The token values MEM, LIB, OBJ, UPD, FIX, or CVRLTR cannot be specified.
An installable object that is packaged with objects from the QSYS.LIB file system cannot contain objects from any other file system.
An installable object that is packaged with objects from the QDLS file system cannot contain objects from any other file system.
This command is shipped with public *EXCLUDE authority
The user to run this command must have the authority necessary to perform the SAVxxx commands over the object to be packaged, to the ADDDSTCLGE command, the Delete File (DLTF) command, Create Save File (CRTSAVF) command, and their required authorities.
At least one *INCLUDE value must be specified in the OBJ parameter
For names involving /QSYS.LIB:
1. OBJ must have only one name.
2. OBJ(object-path-name) must be one of the following:
  - ('/QSYS.LIB/libname.LIB')
  - ('/QSYS.LIB/libname.LIB/*')
  - ('/QSYS.LIB/libname.LIB/*.type')
  - ('/QSYS.LIB/libname.LIB/objname.type')
  - ('/QSYS.LIB/libname.LIB/objname.FILE/*')
  - ('/QSYS.LIB/libname.LIB/objname.FILE/*.MBR')
  - ('/QSYS.LIB/alib.LIB/anobj.FILE/ambr.MBR')
  - ('/QSYS.LIB/*.type')
  - ('/QSYS.LIB/objname.type')
  - ('/QSYS.LIB/filename.FILE/*')
  - ('/QSYS.LIB/filename.FILE/*.MBR')
  - ('/QSYS.LIB/filename.FILE/membername.MBR')
3. .type must be an object type supported by SAVOBJ and RSTOBJ commands
4. .libname cannot be QSYS, QDOC..., QTEMP, QSPL, QSRV, QRECOVERY, or QRPLOBJ if libname.LIB is the last component of the name
5. OBJ(install-to) must be *SAME or '/QSYS.LIB/libname.LIB'
6. SUBTREE must be *ALL
For names involving only /QDLS:
- OBJ must have only one name.
- OBJ (object-path-name install-to) and SUBTREE must be on of the following:
  - ('/QDLS/path/foldername' '/QDLS/path/foldername') SUBTREE(*ALL)
  - ('/QDLS/path/documentname' '/QDLS/path/documentname') SUBTREE(*OBJ)
For names involving other file systems:
- OBJ cannot contain QSYS.LIB or QDLS file systems
For names involving links:
- When a link is used to package an object, a link referring to the same object name must exist in the managed system where the installable object is installed. If the link does not exist in the managed system, the user must also package the link.

Top

Parameters

Keyword	Description	Choices	Notes
GLBNAME	Global name	Element list	Required, Positional 1
	Element 1: Global name token 1	Character value, *NETID
	Element 2: Global name token 2	Character value, DATE, TIME, NETID, CPNAME
	Element 3: Global name token 3	Character value, DATE, TIME, NETID, CPNAME
	Element 4: Global name token 4	Character value, DATE, TIME, NETID, CPNAME
	Element 5: Global name token 5	Character value, DATE, TIME, NETID, CPNAME
	Element 6: Global name token 6	Character value, DATE, TIME, NETID, CPNAME
	Element 7: Global name token 7	Character value, DATE, TIME, NETID, CPNAME
	Element 8: Global name token 8	Character value, DATE, TIME, NETID, CPNAME
	Element 9: Global name token 9	Character value, DATE, TIME, NETID, CPNAME
OBJ	Objects	Values (up to 300 repetitions): Element list	Optional, Positional 2
	Element 1: Name	Path name, *
	Element 2: Include or omit	INCLUDE, OMIT
	Element 3: Install to	Path name, *SAME
SUBTREE	Directory subtree	ALL, DIR, *OBJ	Optional
TGTRLS	Target release	CURRENT, PRV, V5R4M0, V6R1M0, V7R1M0	Optional
AUTL	Authorization list	Name, QCQRPSAUTL	Optional

Top

Global name (GLBNAME)

Specifies the token values of the global name. The global name is the name by which the object is known in a system network architecture (SNA) network. The global name can be a maximum of 65-n characters in length, where n is the number of tokens. A maximum of 9 tokens can be specified and each token can be a maximum of 16 characters in length.

Valid tokens consist of uppercase letters A through Z and numbers 0 through 9. The special characters #, $, or @ may be used. In multi-lingual networks, language translation may make the value not valid when the special characters are used. Use of these characters is not recommended.

Element 1: Token 1

*NETID: The first global name token value is a network ID generated by the command from the network attributes.
global-name-token-1: Specify the first token of the global name. The first token is recommended to be the registered enterprise ID or network ID.

Elements 2-9: Tokens 2-9

*DATE: Identifies the global name token value as the current date. This value is generated from the system value with the format Y1992M04D10.
*TIME: Identifies the global name token value as the current time. This value is generated from the system value with the format H13M30S20.
*NETID: Identifies the global name token n value as a network ID. This value is generated from the network attributes.
*CPNAME: Identifies the global name token value as a control point name. This value is generated from the network attributes.
global-name-token-n: Specify a token of the global name.

Top

Object (OBJ)

Specifies the objects to package and where they will be installed. A maximum of 300 object patterns can be specified.

Element 1: Object Name

'*': All objects in the current directory are saved.
object-path-name: Specify an object path name or a pattern that can match many names. The path name can be up to 5000 characters.

Element 2: Include or Omit

The second element specifies whether names that match the pattern should be included or omitted from the operation.

*INCLUDE: Specify that objects matching the object name pattern are to be packaged, unless overridden by an *OMIT specification.
*OMIT: Specify that objects matching the object name pattern are not to be packaged. This overrides a *INCLUDE specification as is intended to be used to omit a subset of a previously selected pattern.

Element 3: Install to

Specify where the object will be installed.

*SAME: Specify that the objects are to be installed with the same names they had when they were packaged. If *OMIT is specified in the second element, this will be ignored.
install-to: Specifies an object path name or a pattern that can match many names where the object will be installed. If a pattern is specified in element 1, the new name must be the directory into which to install any objects that match the pattern. If *OMIT is specified in the second element, this will be ignored. The path name can be up to 5000 characters.

Top

Directory subtree (SUBTREE)

Specifies whether the directory subtrees are included in the save operation.

*ALL: The entire subtree of each directory that matches the object name pattern is included.
*DIR: Objects in the first level of each directory that matches the object name pattern are included.
*OBJ: Only the objects that exactly match the object name pattern are included. If the object name pattern specifies a directory, objects in the directory are not included.
Note:

When *OBJ is specified in the SUBTREE parameter and install-to is *SAME, the object name pattern must exist in the managed system in order to be installed.

Top

Target release (TGTRLS)

Specifies the release of the operating system on which you intend to use the objects.

*CURRENT: The objects are to be used on the release of the operating system currently running on your system.
*PRV: The objects are to be used on the previous release.
release level: Specify the release level in the format VxRxMx. The objects can be used on a system with the specified release or with any later release of the operating system installed. Valid values depend on the current version, release, and modification level, and change with each new release.

Top

Authorization list (AUTL)

Specifies the name of the authorization list of the objects.

QCQRPSAUTL: The SNA/FS authorization list.
authorization-list-name: The name of the authorization list. The authorization list must already exist.

Top

Examples

Example 1: Packaging All Objects in Current Directory and Subdirectories

PKGINSOBJ   GLBNAME(PACKAGE CURRENT DIRECTORY REF 001)
            OBJ(('*' *INCLUDE *SAME))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all the objects in the current directory and its subdirectories. When installed, the packaged objects are created in the current directory of the user under which the install request runs. The default OBJ value can be used. The current directory is resolved during the packaging.

Example 2: Packaging All Objects in Current Directory

PKGINSOBJ   GLBNAME(PACKAGE CURRENT DIRECTORY NO SUBDIR REF 002)
            OBJ(('*' *INCLUDE *SAME))  SUBTREE(*OBJ)
            TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all the objects in the current directory but not in the subdirectories. The current directory is resolved during the packaging. The objects are installed in the directory specified in the path name that must already exist in the managed system at the time of the installing.

Example 3: Packaging All Objects in Specified Directory

PKGINSOBJ   GLBNAME(PACKAGE A DIRECTORY OMITTING REF 001)
            OBJ(('/A' *INCLUDE *SAME)) ('/A/B/C' *OMIT))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all the objects in directory /A and its subdirectories, except those in directory /A/B/C. If the directory does not already exist, when the objects are installed, the directory /A is created including its subdirectories and their objects.

Example 4: Packaging All Files

PKGINSOBJ   GLBNAME(PACKAGE ALL FILES IN MYLIB REF 003)
            OBJ(('/QSYS.LIB/MYLIB.LIB/*.FILE' *INCLUDE *SAME))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all files in MYLIB. When it is installed, the library MYLIB is created, including its objects.

Example 5: Packaging Object in One Library and Installing Object in Another Library

PKGINSOBJ   GLBNAME(RENAMING OBJECTS WHEN INSTALLING REF 001)
            OBJ(('MyDir/X.PGM' *INCLUDE 'YourDir/Y.PGM'))
            SUBTREE(*ALL)  TGTRLS(*PRV)  AUTL(QCQRPSAUTL)

This command packages program X from MyDir and installs the object in YourDir with Y name. The system where it will be installed is in the previous release.

Example 6: Packaging Objects in Different File Systems

PKGINSOBJ   GLBNAME(PACKAGE A FILE REF 01)
            OBJ(('/MyDir/MyFile' *INCLUDE *SAME))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

PKGINSOBJ   GLBNAME(PACKAGE A DATABASE REF 01)
            OBJ(('/QSYS.LIB/MYLIB.LIB/MYFILE.FILE' *INCLUDE
              *SAME)) SUBTREE(*ALL)  TGTRLS(*CURRENT)
            AUTL(QCQRPSAUTL)

PKGINSOBJ   GLBNAME(PACKAGE A DOCUMENT REF 03)
            OBJ(('/QDLS/MYFLR/MYDOC' *INCLUDE *SAME))
            SUBTREE(*OBJ)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages a stream file MyFile, a database file MYFILE, and a document MYDOC.

For the examples that follow, the following directory should be taken into account:

/A/B
/A/C
/A/D
/A/A1
/A/A1/E
/A/A1/F
/A/A1/G
/A/A1/A2
/A/A1/A2/H
/A/A1/A2/I
/A/A1/A2/J

Example 7: Packaging All Objects from Previous Path Name

PKGINSOBJ   GLBNAME(PACKAGE ALL OBJECTS REF 001)
            OBJ(('../*' *INCLUDE *SAME))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all the objects from the previous path name.

Example 8: Packaging All Objects in the First Level of Each Directory

PKGINSOBJ   GLBNAME(PACKAGE FIRST LEVEL OBJECTS REF 001)
            OBJ(('/A' *INCLUDE *SAME))
            SUBTREE(*DIR)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all the objects in the first level of each directory that matches the object name pattern. The objects that are packaged are:

/A/B
/A/C
/A/D
/A/A1
/A/A1/E
/A/A1/F
/A/A1/G
/A/A1/A2

Example 9: Packaging Only Objects in the Directory

PKGINSOBJ   GLBNAME(PACKAGE ONLY OBJECTS REF 001)
            OBJ(('/A' *INCLUDE *SAME))
            SUBTREE(*OBJ)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages only the objects in the directory. The objects that are packaged are:

/A/B
/A/C
/A/D
/A/A1

Example 10: Packaging All Objects in the User OTHERUSER Home Directory

PKGINSOBJ   GLBNAME(PACKAGE OTHER HOME DIR REF 01)
            OBJ(('/HOME/OTHERUSER' *INCLUDE *SAME))
            SUBTREE(*ALL)  TGTRLS(*CURRENT)  AUTL(QCQRPSAUTL)

This command packages all objects from the OTHERUSER home directory.

Top

Error messages

*ESCAPE Messages

CPF2105: Object &1 in &2 type *&3 not found.
CPF2110: Library &1 not found.
CPF2283: Authorization list &1 does not exist.
CPF3781: Library &1 not found.
CPF3826: *INCLUDE object required on OBJ parameter.
CPF382C: OBJ parameter value not valid for QSYS file system.
CPF382F: OBJ parameter value not valid for QDLS file system.
CPF5702: File either not DDM file or not found.
CPF9802: Not authorized to object &2 in &3.
CPF9838: User profile storage limit exceeded.
CPF9870: Object &2 type *&5 already exists in library &3.
MSS0114: Not authorized to distribution catalog.
MSS0116: Maximum global name length exceeded.
MSS0117: Global name token &3 not valid. Reason code &4.
MSS011B: Distribution catalog entry not found.
MSS0123: Internal processing error occurred.
MSS0124: Error while managing distribution catalog.
MSS0125: Distribution catalog damaged.
MSS0133: Not authorized to add distribution catalog entry.
MSS0136: Global name already exists.
MSS02EF: Not authorized to user profile &1.
MSS02F0: User profile &1 not found.
MSS02F1: User profile &1 not accessible.
MSS02F6: Installable object not packaged.
MSS02F7: Global name not valid for installable object.
MSS02F8: &1 objects packaged. &2 objects not packaged.
MSS02F9: Parameters not valid with multiple file systems.
MSS02FA: SUBTREE should be *ALL when QSYS is specified.

Top