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.
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.
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
.
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 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.
The name of the format containing the directory list. The valid format names
are:
DIRI0100
Use this format if your product contains full path names
which will not exceed 240 characters in length. For more information, see DIRI0100
Format.
DIRI0200
Use this format if your product contains full path names
which may exceed 240 characters. For more information, see DIRI0200
Format.
Note: If your product load has a preoperation or postoperation exit program, then carefully consider the value specified on this parameter. If your product load is created with directory list format DIRI0200, you must code your exit program to handle directory names up to 1024 characters in length, even if none of your directories currently exceeds 240 characters. For more information on the format used during exit program processing, see the Software Product Functions Exit Program documentation.
Note: The total length of all the full paths in the directory list can not exceed 2,500,000 bytes if the API is called from a job running in a single byte character set. The limit is 5,000,000 bytes if the API is called from a job running in a double byte character set.
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.
The product load information parameter is described in the following table.
For a detailed description of the fields in the table, see Field Descriptions.
The principal library information parameter is described in the following
table. For a detailed description of the fields in the table, see Field Descriptions.
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.
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.
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.
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.
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.
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.
Additional development library name. The name of the
additional development library.
Additional primary library name. The additional primary
library name. Valid special values are:
*DVLLIB
The development library name is used as the
primary library name.
*CODE
The additional primary library in the code load
corresponding to the immediately preceding development library is used. This
value is valid only when the product load type is specified as *LNG in the
product load information parameter.
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:
*PRDDFN
Specify this value if:
You want the preoperation exit program to be associated with the principal
development library.
You specified *PRDDFN for the principal development library field of the
principal library information parameter.
This is only valid when *PRDDFN is specified for the principal development
library in the principal library information parameter.
*CODE
Specify this value if you want the preoperation
exit program to be associated with the principal development library and if you
specified *CODE as the principal development library field of the principal
library information parameter. This is only valid when *CODE is specified for
the principal development library in the principal library information
parameter.
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:
DIRI0100
When using this directory list format, the full path
length is limited to 240 characters.
DIRI0200
When using this directory list format, the full path
length is limited to 1024 characters.
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, 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:
*CODEDFT
The default code load ID, 5001, is used. This
value is valid only when the product load type field is *CODE.
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:
*CURRENT
The version, release, and modification level of
the operating system is used.
*PRV
The version, release, and modification level
previous to that of the operating system is used. Previous is the previous
release with modification level 0 of the operating system.
*CODE
The minimum target release of the code load for
this option is used.
*BASECODE
The minimum target release of the code load for
the base option is used.
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:
*NONE
No exit program is called after the library is
saved, restored, or checked.
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.
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:
*DVLFLR
The development folder name is the same as the
primary folder name.
Principal development library name. The library into which
the product load is created. Valid special values are:
*PRDDFN
The name of the library in which the product
definition exists is used for the development library name.
*CODE
The name of the principal development library for
the code load is used. This value is valid only when the product load type
field is specified as *LNG.
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:
*DVLLIB
The development library name is used as the
primary library name.
*CODE
The name of the principal development library for
the code load is used. This value is valid only when the product load type
field is specified as *LNG.
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:
*CODE
A code load is created.
*LNG
A language load is created.
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:
*PRDDFN
The registration ID is taken from the product
definition for this product and release level. The product definition must
exist for *PRDDFN to be valid.
*PHONE
A telephone number will be entered in the
registration ID value field.
*CUSTOMER
The country or region code and IBM® customer number will be
entered in the registration ID value field.
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 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:
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:
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'.
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.
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:
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.
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.
Language
Suffix
Language
Suffix
Albanian
_sq
Arabic
_ar
Bulgarian
_bg
Byelorussian
_be
Catalan
_ca
Croatian
_hr
Czech
_cs
Danish
_da
Dutch
_nl
English
_en
Estonian
_et
Finnish
_fi
French
_fr
German
_de
Greek
_el
Hebrew
_iw
Hindu
_hi
Hungarian
_hu
Icelandic
_is
Italian
_it
Japanese
_ja
Korean
_ko
Laotion
_lo
Latvian
_lv
Lithuanian
_lt
Macedonian
_mk
Polish
_pl
Norwegian
_no
Portugese
_pt
Portugese
_pt_BR
Romanian
_ro
Russian
_ru
Serbian
_sr
Simplified Chinese
_zh_CN
Slovakian
_sk
Slovenian
_sl
Spanish
_es
Swedish
_sv
Thai
_th
Traditional Chinese
_zh_TW
Turkish
_tr
Ukranian
_uk
Vietnamese
_vi
Error Messages
Message ID
Error Message Text
CPF0CA1 E
No language load defined.
CPF0CA2 E
Code load ID &9 not valid.
CPF0CA3 E
Code load &4 supported.
CPF0CB1 E
Registration identifier not valid.
CPF0CB2 E
Product identifier &1 not valid.
CPF0CB3 E
Value for reserved field not valid.
CPF0C1B E
Requirements between parameters not
satisfied.
CPF0C16 E
Object &1 type &3 already exists in
library &2.
CPF0C17 E
*&3 object already exists for product &4
release &5.
CPF0C18 E
Registration identifier &7 not valid for
product &4 release &5.
.