Create Product Load (QSZCRTPL) API

The Create Product Load (QSZCRTPL) API creates a product load (*PRDLOD) object. Each release of a software product requires one or more product load objects.

Authorities and Locks

Library Authority

*ADD and *READ

Library Lock

*SHRUPD

Product Availability Lock

*SHRRD. The product availability object resides in the QUSRSYS library.

Required Parameter Group

Product load name

INPUT; CHAR(10)

The name of the product load object to be created. The product load is created into the principal development library. The following special value is valid:

*LNG	The name of the load object is the same as the previously created language load object for this product; version, release, and modification level; and option. This special value is only valid if a language product load is being created.

Product load information

INPUT; CHAR(87)

A structure containing information about the product load. For more information, see the Format of Product Load Information.

Secondary language library name

INPUT; CHAR(10)

The name of the secondary language library for the language product load being created. This is the library into which this product load is installed if:

• The language identifier for this product load does not match the system primary language identifier.
• No override name is specified on the Restore Licensed Program (RSTLICPGM) command.

This field is valid only if a language product load is being created.

Principal library information

INPUT; CHAR(30)

The first 10 characters specify the principal development library. The second 10 characters specify the principal primary library. The last 10 characters specify the postoperation exit program for both principal libraries. For more information, see Format of Principal Library Information.

Additional library list

INPUT; ARRAY of CHAR(30)

The additional libraries for the product load. Additional libraries do not need to exist before the product load object is created.

For each element:

• The first 10 characters specify the development library.
• The second 10 characters specify the primary library.
• The last 10 characters specify the postoperation exit program for both libraries.

For more information, see Format of Additional Library List.

Number of additional libraries

INPUT; BINARY(4)

The number of elements in the additional library list. If the number of elements in the additional library list is less than the value specified, the results are unpredictable.

Preoperation exit programs

INPUT; ARRAY of CHAR(20)

The preoperation exit programs for this load. The first 10 characters specify the exit program name. The second 10 characters specify the development library name. For more information, see Format of Preoperation Exit Programs.

Number of preoperation exit programs

INPUT; BINARY(4)

The number of elements in the preoperation exit programs array. If the number of elements in the preoperation exit programs parameter is less than the value specified, the results are unpredictable.

Folder list

INPUT; ARRAY of CHAR(126)

The folders for this product load. When creating a code load, the first folder specified must be a root folder. When creating a language load, the first folder specified must be a subfolder of a root folder. The folders do not need to exist before the product load object is created.

Each product option has at most one root folder. A folder cannot belong to more than one product option. The root folder must be part of the code load. Folders must be specified so that a parent folder precedes its subfolder on the list.

The number of folders must be zero if the number of directories names in the directory list parameter is greater than zero.

A maximum of 100 folders can be specified for a load.

The documents in the development folders are saved when the product load is saved with the Save Licensed Program (SAVLICPGM) command. For more information, refer to the System Manager Use book .

For each element of the folder list, the first 63 characters specify the development folder and the next 63 characters specify the primary folder. For more information, see Format of Folder List.

Number of folders

INPUT; BINARY(4)

The number of elements in the folder list array. If the number of elements in the folder list is less than the value specified, the results are unpredictable.

Text description

INPUT; CHAR(50)

Text that briefly describes the product load object.

Public authority

INPUT; CHAR(10)

The authority you give to users:

• Who do not have specific authority to the product load object.
• Whose group profile has no specific authority to the object.

Valid values are:

*ALL	Allows the user to perform all operations on the object except those limited to the owner or controlled by the authorization list management authority.
*CHANGE	Allows the user to perform all operations on the object except those: Limited to the owner. Controlled by the object existence authority and object management authority.
*EXCLUDE	Prevents the user from accessing the object.
*LIBCRTAUT	The public authority for the object is taken from the value of the create authority (CRTAUT) parameter of the target library. (This is the library that is to contain the object). This value is determined when the object is created. If the CRTAUT value for the library changes after the object is created, the new value does not affect any existing objects.
*USE	Provides object operational authority and read authority.

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

Directory list

INPUT;CHAR(*)

The directories for this product load. You cannot specify directory names if any folder names are specified in the folder list parameter. A maximum of 300 home directories and a total of 5000 directory full path names can be specified for a load. For more information, see DIRI0100 Format.

Number of directories

INPUT;BINARY(4)

The number of elements in the directory list array. If the number of elements in the directory list is less than the value specified, the results are unpredictable.

Directory list format name

INPUT; CHAR(8)

The name of the format containing the directory list. The format name is:

DIRI0100

See DIRI0100 Format.

Optional Parameter Group 2

Software agreement document list

INPUT; CHAR(*)

The software agreement documents for this product option. The software agreement documents do not need to exist before the product load object is created. The software agreement documents must be created into a directory in '/QIBM/UserData/LicenseDoc' prior to successfully packaging the product option. For more information, see Format of Software Agreement Document List.

Number of software agreement documents

INPUT; BINARY(4)

The number of elements in the software agreement document list array. There must be a minimum of one and a maximum of ten for software agreements to be enabled for a product load. If the number of elements in the software agreement document list is less than the value specified, the results are unpredictable.

Format of Product Load Information

The product load information parameter is described in the following table. For a detailed description of the fields in the table, see Field Descriptions.

Format of Principal Library Information

The principal library information parameter is described in the following table. For a detailed description of the fields in the table, see Field Descriptions.

Format of Additional Library List

The following table describes the additional library list parameter. The offsets shown in the table are for the first element in this array. For a detailed description of the fields in the table, see Field Descriptions.

Format of Preoperation Exit Programs

The following table describes the preoperation exit programs parameter. The offsets shown in the table are for the first element in this array. For a detailed description of the fields in the table, see Field Descriptions.

Format of Folder List

The following table describes the folder list parameter. The offsets shown in the table are for the first element in this array. For a detailed description of the fields in the table, see Field Descriptions.

DIRI0100 Format

The following table describes the directory list parameter. The offsets shown in the table are for the first element in this array. The decimal and hexadecimal offsets to subsequent entries are determined by using the length of the full path length field, the length of the home directory length field, and the value of the full path length field. For a detailed description of the fields in the table, see Field Descriptions.

Format of Software Agreement Document List

The following table describes the software agreement document list parameter. The offsets shown in the table are for the first element in this array. For a detailed description of the fields in the table, see Field Descriptions.

Field Descriptions

Additional primary library name. The additional primary library name. Valid special values are:

Development folder. The name of a development folder for this load. The folder does not need to exist before the product load object is created.

Development library name. The development library with which the preoperation exit program is associated. The preoperation exit program may be associated with the principal library or an additional library. If associated with the principal library, this must be the same as the value for the principal development library in the principal library information parameter. If associated with an additional library, this must be the same as one of the values for the additional development library in the additional library list parameter. Valid special values are:

Full path length. The length of the full path name, in bytes.

Full path name. The fully qualified directory name assigned to this product load. Naming restrictions for directories assigned to a product load include:

• You cannot specify /QSYS.LIB and /QDLS directories.
• You must specify unique full path names.
• You cannot end the path name with a forward slash.
• You cannot use the "." or ".." directories in the path name.
• You cannot use "//" in the directory path name.

Home directory length. The length of the home directory part of the full path name.

Load ID. The load ID of the product load to be created. For language loads, this must be a valid national language version (NLV). The following special value is valid:

Minimum target release. The minimum release of the operating system to which the SAVLICPGM command allows the product to be saved. The format is VxRyMz. Valid values for x, y, and z are 0 through 9. For example, V3R1M0 is Version 3, Release 1, Modification 0. If this field is blank, the version, release, and modification level of the operating system is used. This value may be different for each load, however, the code load must specify the earliest release for a given option. Also, the code load for the base option must specify the earliest release for a given product. Valid special values are:

Postoperation exit program name. The program that is called in the corresponding installed library after any of these operations are performed on the product load:

• Save, using the Save Licensed Program (SAVLICPGM) command
• Restore, using the Restore Licensed Program (RSTLICPGM) command
• Check, using the Check Product Option (CHKPRDOPT) command

The exit program does not need to exist before the product load object is created. The following special value is valid:

Preoperation exit program name. The name of the preoperation exit program. A preoperation exit program is called before any of these operations are performed on the library:

• Save, using the Save Licensed Program (SAVLICPGM) command
• Restore, using the Restore Licensed Program (RSTLICPGM) command
• Delete, using the Delete Licensed Program (DLTLICPGM) command.

Primary folder. The primary folder name associated with the development folder. The following special value is valid:

Principal development library name. The library into which the product load is created. Valid special values are:

Principal primary library name. The product load is installed into this library when no override name is specified on the Restore Licensed Program (RSTLICPGM) command. Valid special values are:

Product ID. The 7-character identifier of the product for which a product load is being created. The product ID must be in the format nlxxxxx, where n is any numeric character 0 through 9. The l is any uppercase letter A through Z, and x is any numeric character 0 through 9 or uppercase letter A through Z.

Product load type. Whether the product load being created is a code load or a language load. Valid values are:

Product option. The product option for which a product load is being created. Use 0000 for the base option.

Registration ID type. Specifies what the registration ID value field represents. Valid values are:

Registration ID value. Identifier of the organization to which the product belongs. This number should be unique from other vendors on the systems on which this product will be installed. It is recommended that you specify a telephone number, including the country or region and city code, or specify your country or region code followed by your IBM customer number. Valid characters for the registration ID value are A through Z and 0 through 9, padded with blanks on the right.

Release level. The version, release, and modification level of the product being created 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, V2R1M0 is Version 2, Release 1, Modification 0.

Reserved. This field must contain blank characters; otherwise, an error occurs.

Software agreement document length. The length of the software agreement document in bytes.

Software agreement document name. The name of the software agreement document. For products using software agreements, the software agreement documents do not have to exist at the time the product load is created but must exist when the product option is packaged and must reside in a specific directory structure in IFS. The software agreement document repository is '/QIBM/UserData/LicenseDoc'. Each software agreement document must have its own subdirectory under '/QIBM/UserData/LicenseDoc'. The subdirectory must be named the same as the software agreement document. Each of these subdirectories must contain the actual software agreement document(s), translated for your supported languages, stored in UTF 16 (Big Endian). See Generate online software agreements for instructions on creating software agreements in UTF 16. Additionally, each document name within the subdirectory must contain the appropriate language extension that matches the supported languages. See Approved Language Suffixes for a full list.

The following example provides guidance concerning the naming of software agreement documents:

Assumptions:

• The product load being created is going to be enabled for software agreements.
• The product load being created includes three software agreement documents, translated in English and French, that need to be accepted prior to the product option being successfully installed on the system.
• The software agreement documents for this product load are named as follows:
  1. document 1: 1MYPROD-V7R4M1-0000-01_en (English translation) 1MYPROD-V7R4M1-0000-01_fr (French translation)
  2. document 2: 1MYPROD-V7R4M1-0000-02_en (English translation) 1MYPROD-V7R4M1-0000-02_fr (French translation)
  3. document 3: 1MYPROD-V7R4M1-0000-03_en (English translation) 1MYPROD-V7R4M1-0000-03_fr (French translation)

Actions to perform:

1. In the '/QIBM/UserData/LicenseDoc' directory create three sub-directories with the names '1MYPROD-V7R4M1-0000-01', '1MYPROD-V7R4M1-0000-02', and '1MYPROD-V7R4M1-0000-03'.
2. Within the appropriately named directory just created, put the correct document(s). All translated versions of document 1 ( from the example these are 1MYPROD-V7R4M1-0000-01_en, 1MYPROD-V7R4M1-0000-01_fr) will be located in the following directory: 'QIBM/UserData/LicenseDoc/1MYPROD-V7R4M1-0000-01'. Similarly, document 2 (1MYPROD-V7R4M1-0000-02_en, 1MYPROD-V7R4M1-0000-02_fr), and document 3 (1MYPROD-V7R4M1-0000-03_en, 1MYPROD-V7R4M1-0000-03_fr) will have to be located under their respectively named directories.
3. A specific language identifier must be appended to the document name for each language the document is available in. Currently there are 43 recognized language suffixes valid for software agreements. See Approved Language Suffixes for a full list.

The naming restrictions on the software agreements document name assigned to a product load include:

• Software agreement document name must be 80 or fewer characters long.
• To prevent naming conflicts with other software agreement documents, the software agreement documents must be uniquely named. One suggestion for uniquely naming your software agreement documents would be:
  • Insert the Product ID - Version/Release/Modification - Option information for the product load into the document name. Example:
    • Product: 1MYPROD, Version/Release/Modification: V7R4M1, Option: 0002
    • Software agreement document name: 1MYPROD-V7R4M1-0002
• Software agreement documents must be located in a directory with the same name as the document in the '/QIBM/UserData/LicenseDoc' directory.
• Software agreement documents must have a language identifier appended to the document name. Note: The directory name in which the document is located will not contain a language identifier, only the document name will contain the suffix.
  • From the previous example, you would create the directory '/QIBM/UserData/LicenseDoc/1MYPROD-V7R4M1-0002'. Then for each language the document will be available in, create a file named '1MYPROD-V7R4M1-0002_nn' (where '_nn' signifies the language of this document) in this directory. See Approved Language Suffixes for a full list of recognized languages.
• Software agreement documents must be stored in UTF 16 (Big Endian). See Generate online software agreements for more details on creating and storing your software agreements in UTF 16.

Approved Language Suffixes

The following table displays the language suffixes recognized in V5R2M0 that may be used to identify the translated software agreement documents for this product load.

Error Messages