Select Product (QSZSLTPR) API
Required Parameter Group:
| 1 | Output List | Output | Array of Char(*) |
| 2 | Input information | Input | Char(40) |
| 3 | Format name | Input | Char(8) |
| 4 | Input list | Input | Array of Char(18) |
| 5 | Output information | Output | Char(12) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Select Product (QSZSLTPR) API displays a list of products. One or more products can then be selected from the prompt screen. The list of selected products is then returned to the caller of the API. The list of products displayed can be:
- All installed products.
- All supported products.
- All defined products.
- A user-specified subset of all defined products.
- All products that are supported, installed, or both installed and supported.
Alternatively, the QSZSLTPR API can return a list of products without displaying a list of products. The result is as if the list of products had been displayed and all products in the list had been selected.
If the job is in batch mode, the number of products to select field must be *ALL.
Note: A product can be supported and unsupported by using the Work with Supported Products (WRKSPTPRD) command. This command is part of the IBM® System Manager for i licensed program.
A defined product is one which is known to the system. This includes all installed products, but also includes products which are known to the system without the products being installed. For example, V5R4M0 of the System Manager for IBM i licensed program (5722SM1) is known to the system once V5R4M0 of the operating system is installed. Therefore V5R4M0 of 5722SM1 is a defined product once V5R4M0 of the operating system is installed.
A product is also a defined product when a product definition (*PRDDFN) object exists for that product on the system.
Authorities and Locks
- *PRDAVL Lock
- *SHRRD
Required Parameter Group
- Output list
- OUTPUT; Array of CHAR(*)
An array where you will receive one or more product records.
All the records of this array will have the same size. The size is returned in the record size field of the output information parameter.
When the number of products to select field of the input information parameter is:
*ONE The output array must be able to contain at least one record or the results are unpredictable. *ALL The array contains a complete list of product ID records as if all product IDs were selected. No display is shown. If you do not provide enough space for all the records, as many records as can be returned in the space provided will be returned. The Records available field of the Output information parameter will indicate the number of records that were available to be returned. *ANY The array contains a list of product ID records selected from the display. It is assumed that you can select all of the product IDs shown on the display. Therefore, the output array has to be able to hold all the records shown on the display. This is checked before the display is shown. If the output array cannot hold all of the available records, an error message is returned and no display is shown. For information about the layout of this parameter, see PRDS0100 Format and PRDS0200 Format.
- Input information
- INPUT; CHAR(40)
Specifies:
- The number of records to be returned.
- Whether a list of products is to be displayed for selection or whether no list is to be displayed.
- Several attributes of the display if the list is to be displayed for selection.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned.
The possible format names are:
PRDS0100 Basic information is returned. See PRDS0100 Format. PRDS0200 This format includes more information than format PRDS0100. See PRDS0200 Format.
- Input list
- INPUT; Array of CHAR(18)
An array containing the records used to determine which products that are defined to the system are displayed or returned. The Input list is ignored unless the Product field is equal to *LIST. The format of the data for the input list is described in Input List Format.
- Output information
- OUTPUT; CHAR(12)
The following information is returned:
- The size of an output record.
- The number of records available.
- An indicator of what action was performed on the display.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Input Information Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of records to return |
| 4 | 4 | CHAR(10) | Number of products to select |
| 14 | E | CHAR(1) | Initial panel view |
| 15 | F | CHAR(1) | Allow exit |
| 16 | 10 | CHAR(10) | Product options to display |
| 26 | 1A | CHAR(10) | Product |
| 36 | 24 | BINARY(4) | Records in list |
Field Descriptions for Input Information
When *LIST is specified for Product, then a list of product records must be specified for the Input List parameter.
Allow exit. Whether the exit action is allowed from the display.
The valid values are:
| 1 | Exit and cancel are both allowed. |
| 0 | Only cancel is allowed. |
Initial panel view. Whether the first view of the display shows the release level.
If the release level is shown on the first view, the description is not shown until the view is changed by pressing the appropriate key. If the first view does not show the release level, the appropriate key can be pressed to change the view and show the release level.
The valid values are:
| 1 | The initial view of the display shows the release level. |
| 2 | The initial view of the display shows the description text. |
Number of products to select. The number of products that are allowed to be selected on the display. This field controls whether a panel is displayed or not.
The valid values are:
| *ONE | One product is allowed to be selected. If the job is in batch mode, CPF0C1A will be returned. |
| *ANY | Any number of products can be selected. If the job is in batch mode, CPF0C1A will be returned. |
| *ALL | No list is displayed; all the products will be selected. |
Number of records to return. The number of records that can be put in the output list array.
Product. If the Number of products to select parameter is *ALL, this field specifies which products to return. Otherwise, this field specifies which products to put in the list of products to display.
The valid values are:
| *INSTLD | Installed products. Installed means that a product definition (*PRDDFN) object and a product load (*PRDLOD) object for the code load were loaded onto the system by the Restore Licensed Program (RSTLICPGM) command. |
| *SUPPTD | Supported products. Products supported by using the Work with Supported Products (WRKSPTPRD) command which is part of the System Manager for IBM i licensed program. |
| *INSSPT | Installed or supported products. All products that are installed, supported, or both installed and supported. |
| *ALL | All known and defined products. This includes installed and supported and others that are not installed or supported. |
| *LIST | The list of products shown on the display or returned is derived from the list that is passed in the Input List array. The API builds a list of product ID, product option, release level combinations from the Input List parameter. See Field Descriptions for Input List for information. |
Product options to display. Whether only the base option of each product is to be displayed or whether all options are to be displayed.
The valid values are:
| *ALL | Show all options of a product |
| *BASE | Show only the base option of a product |
Records in list. The number of records in the Input List array. This is used only when the Product field is equal to *LIST.
Output Information Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Record size |
| 4 | 4 | BINARY(4) | Records available |
| 8 | 8 | BINARY(4) | Action |
Field Descriptions for Output Information
Action. What action was performed on the display. If no display was shown, 0 is returned.
The possible values are:
| -4 | Exit |
| -8 | Cancel |
| 0 | Enter |
| 21 | Select all |
Records available. The number of records that are available to be returned.
If a panel is displayed and either the exit or cancel action is performed, (so no records were selected) this number is 0.
If no records are shown on the display, or no records are returned in the output array, this number will be equal to minus 1.
*ANY may be specified for the Number of products to select parameter. If so, in case of an error, this number indicates the necessary size of the output array. More storage is required for the API and no list is returned.
*ALL may be specified for the Number of products to select parameter. If so, this number indicates whether there were more records to return in the output array; a partial list may have been returned.
Record size. The length of the records of the output array.
- When format PRDS0100 is requested, this value is 83.
- When format PRDS0200 is requested, this value is 197.
Input list and Output list Formats
The output list parameter can be in one of two formats. See PRDS0100 Format, and PRDS0200 Format for information.
Input List Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Product ID |
| 7 | 7 | CHAR(5) | Product option |
| 12 | C | CHAR(6) | Release level |
Field Descriptions for Input List
When *LIST is specified for the Product parameter, then a list of product records must be specified for the Input List parameter. The API builds a list of product ID, product option, release level combinations from the Input List parameter. All product ID, product option, release level combinations defined to the system, which match a record in the Input List, are put into a list. The list is displayed or returned.
Any combination of the product ID, product option, and release level fields can be left blank. A blank field matches all values for that field. For example, a product ID and product option are specified. But if the release level field is left blank, all available releases of the specified product option are displayed or returned.
If the Product ID, Product option, and Release level are all blank, all available products at all release levels are displayed or returned.
Product ID. The product IDs to display or return. The product ID must be a valid product ID for a defined product or blank. If the API does not find a valid product ID from the defined products, an error is returned.
Product option. The product option to display or return. The product option must be blank or a valid product option must be specified. Valid values are *BASE (00000), 00001, 00002, 00003, and so on. Leading zeros are required.
Release level. The version, release, and modification level of the product.
The release level can be passed as one of the following two formats:
| VxRyMz | Where x is any numeric character 0 through 9, y is any numeric character 0 through 9, and z is any numeric character 0 through 9 or uppercase letter A through Z. For example, V7R2M0 is version 7, release 2, modification 0. |
| vvrrmm | Where vv are any numeric characters 00 through 35 representing the version of the product, rr are any numeric characters 00 through 35 representing the release of the product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the product. For example, 110300 is version 11, release 3, modification 0. This format must be used if the version or release of the product is greater than 9. |
PRDS0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Product ID |
| 7 | 7 | CHAR(5) | Product option |
| 12 | C | CHAR(6) | Release level |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | CHAR(7) | Description text message ID |
| 27 | 1B | CHAR(10) | Description text object name |
| 37 | 25 | CHAR(46) | Description text |
PRDS0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Product ID |
| 7 | 7 | CHAR(5) | Product option |
| 12 | C | CHAR(6) | Release level |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | CHAR(7) | Description text message ID |
| 27 | 1B | CHAR(10) | Description text object name |
| 37 | 25 | CHAR(10) | Description text library name |
| 47 | 2F | CHAR(1) | Installed flag |
| 48 | 30 | CHAR(1) | Supported flag |
| 49 | 31 | CHAR(2) | Registration type |
| 51 | 33 | CHAR(14) | Registration value |
| 65 | 41 | CHAR(132) | Description text |
Field Descriptions for output list
Description text. Text in the message that describes the product option selected. To retrieve the message text, the library list is searched for the specified message file. If the message file is not found, then the description text library name is used to try to retrieve the message text. If the message file is not found, blanks are returned.
Note: This field is only 46 characters long for format PRDS0100 because product descriptions typically should not be longer than 46 characters. Product descriptions should not be longer than 46 characters because some system commands display a maximum of 46 characters for each product description.
Description text library name. The name of the library for the message file that contains the messages which describe the product and its options.
Description text message ID. A seven character alphanumeric identifier assigned to the message that describes the product option selected. The message ID for the base option is the message ID for the product.
Description text object name. The name of the message file that contains the messages which describe the product and its options.
Installed flag. Whether the code load for this product option is installed or not. A load is installed if a product load (*PRDLOD) object is loaded on the system by the Restore Licensed Program (RSTLICPGM) command.
The possible values are:
| 1 | The code load is installed. |
| 0 | The code load is not installed. |
Product ID. The product ID selected.
Product option. The product option of the product selected.
Registration type. The registration type associated with the product. The registration type and registration value together make up the registration ID for the product.
Registration value. The registration value associated with the product. The registration type and registration value together make up the registration ID for the product.
Release level. The release level of the product selected.
The release level can be returned in two possible formats:
| VxRyMz | Where x is the version of the product, y is the release of the product, and z is the modification of the product. For example, V7R2M0 is version 7, release 2, modification 0. This format will always be returned when the version and release are both less than or equal to 9. |
| vvrrmm | Where vv is the version of the product, rr is the release of the product, and mm is the modification of the product. For example, 110300 is version 11, release 3, modification 0. This format will be returned if the version or release of the product is greater than 9. |
Reserved. This field will contain blanks.
Supported flag. Whether this load is currently supported. A load can be supported by using the Work with Supported Products (WRKSPTPRD) command in the System Manager for IBM i licensed program.
The possible values are:
| 1 | The load is supported. |
| 0 | The load is not supported. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0C10 E | Input information parameter at offset &3 is not valid. |
| CPF0C11 E | Products listed in Input List array not found. |
| CPF0C12 E | Output List array too small. |
| CPF0C15 E | Error occurred while processing QSZSLTPR API. |
| CPF0C1A E | Panel could not be displayed. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF6A00 E | All CPF6Axx messages could be returned. xx is from 01 to FF. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R1