Create Product Load (QSZCRTPL) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  Default Public Authority: *EXCLUDE

  Threadsafe: No

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:


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 manual Link to PDF.

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:


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 on the format of the directory list, see Directory list format name.

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 valid format names are:


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 when using directory list format DIRI0100. 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.



DIRI0200 Format

The following table describes the directory list parameter when using directory list format DIRI0200. 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.


Note: Format DIRI0200 is only valid for product loads with a minimum target release value of at least V6R1M0.



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 development library name. The name of the additional development library.

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 characters. The characters in the full path may be single-byte or double-byte. The maximum number allowable full path length is the same for double-byte data and single-byte data. The maximum allowable full path length varies between directory list format DIRI0100 and directory list format DIRI0200. The following table details the difference:

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

Home directory length. The length of the home directory part of the full path name, in characters. The characters in the home directory may be single-byte or double-byte. The home directory length is limited to 240 characters whether the data is double-byte or single-byte. The maximum length of the home directory is the same with directory list format DIRI0100 and directory list format DIRI0200.

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:

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:

The exit program does not need to exist before the product load object is created.

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.

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

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 Generating software agreements for your own products 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:


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:


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



API Introduced: V2R3

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