Map Release (QSZMPRLS) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format | Input | Char(8) |
| 4 | Release information | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Map Release (QSZMPRLS) API will map a Version/Release/Modification (VRM) value from one of three input formats to three distinct formats used to support IBM i Licensed Programs. This API will also sort, in ascending order, two or more VRM values of potentially different formats.
Authorities and Locks
- Public API Authority
- None
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable to receive the requested information. This information will be the mapped or sorted release values based on the input values. The output values are determined by the format name.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable in bytes. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format
- INPUT; CHAR(8)
The content and format for the information returned.
The possible format names are:
MVRM0100 Returns the VRM value mapped to three supported Licensed Program VRM formats. For more information, see MVRM0100 Format. MVRM0200 Returns a list of one or more releases. For more information, see MVRM0200 Format.
- Release information
- INPUT; CHAR(*)
The VRM value to map to the supported formats or the list of VRM values to sort in ascending order. For more information, see Release Information Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Release Information Format
Information passed in the input release information parameter must be in the following format. For detailed descriptions of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of entries |
| 4 | 4 | BINARY(4) | Length of one release value entry |
| Note: The fields repeat for each release value entry. | |||
| The decimal and hexadecimal offsets are determined by using the length of one release value entry. | CHAR(10) | Release | |
| CHAR(8) | Release format | ||
Receiver Variable Format
MVRM0100 Format
The following describes the format of the mapped release information returned in the receiver variable parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(3) | Three-character release |
| 7 | 7 | CHAR(6) | Six-character release |
| 13 | D | CHAR(10) | Displayable release |
MVRM0200 Format
The following describes the format of the sorted release information returned in the receiver variable parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to three-character release entries |
| 12 | C | BINARY(4) | Number of three-character release entries |
| 16 | 10 | BINARY(4) | Length of three-character release entry |
| 20 | 14 | BINARY(4) | Offset to six-character release entries |
| 24 | 18 | BINARY(4) | Number of six-character release entries |
| 28 | 1C | BINARY(4) | Length of six-character release entry |
| 32 | 20 | BINARY(4) | Offset to displayable release entries |
| 36 | 24 | BINARY(4) | Number of displayable release entries |
| 40 | 28 | BINARY(4) | Length of displayable release entry |
| Note: The fields repeat for each release value entry. | |||
| The decimal and hexadecimal offsets are determined by using the length of one release value entry. | Array(*) of CHAR(3) | Three-character release | |
| Array(*) of CHAR(6) | Six-character release | ||
| Array(*) of CHAR(10) | Displayable release | ||
| Note: If more than one entry is returned in the array, the entries are sorted by earliest release to latest release. | |||
Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes returned to the user. This is the lesser of the number of bytes available and the length of the receiver variable.
Displayable release. The VRM value in a displayable format. This represents the VRM value as it would appear on a useable interface. The value will be in the format VxxRyyMz where xx is any numeric character 0 through 35, yy is any numeric character 0 through 35, and z is any numeric character 0 through 9 or uppercase letter A through Z. For example, V10R12MX is version 10, release 12, modification X. Leading zeros are left out.
Length of displayable release entry. The length of each displayable release entry.
Length of six-character entry. The length of each six-character release entry.
Length of three-character release entry. The length of each three-character release entry.
Number of displayable release entries. The number of displayable release entries.
Number of entries. The number of release entries passed in the Release information parameter.
Number of six-character release entries. The number of six-character release entries.
Number of three-character release entries. The number of three-character release entries.
Offset to displayable release entries. The offset from the beginning of the receiver variable to the start of the list of displayable release entries.
Offset to six-character release entries. The offset from the beginning of the receiver variable to the start of the list of six-character release entries.
Offset to three-character release entries. The offset from the beginning of the receiver variable to the start of the list of three-character release entries.
Release. The (release) VRM value. This value is required.
Release format. The format for the release field. The possible values are:
| VRMF0100 | The input VRM value is a three character representation of the release of the product. The first character represents the Version of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are mapped to numeric values 10 (A) through 35 (Z). The second character represents the Release of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are mapped to numeric values 10 (A) through 35 (Z). The third character represents the Modification of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are not mapped and are interpreted as alphabetic values. |
| VRMF0200 | The input VRM value is a six character representation of the release of the product with no 'V'. 'R', or 'M' characters. The first two characters represent the Version of the product, and valid values range from 00 to 35. The second two characters represent the Release of the product, and valid values range from 00 to 35. The third two characters represent the Modification of the product, and valid values range from 00 to 09, and 0A through 0Z. Values 0A through 0Z are not mapped and are interpreted as alphabetic values. |
| VRMF0300 | The input VRM value is an up to ten character representation of the release of the product with the 'V'. 'R', or 'M' characters included. Preceding zeros are not necessary. The input value is parsed and separated based on the location of the 'V', the 'R', and the 'M'. The characters immediately following the 'V' represent the Version of the product, and valid values range from 0 to 35. The characters immediately following the 'R' represent the Release of the product, and valid values range from 0 to 35. The characters immediately following the 'M' represent the Modification of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are not mapped and are interpreted as alphabetic values. |
Six-character release. The value is a six character representation of the release of the product with no 'V'. 'R', or 'M' characters. The first two characters represent the Version of the product, and valid values range from 00 to 35. The second two characters represent the Release of the product, and valid values range from 00 to 35. The third two characters represent the Modification of the product, and valid values range from 00 to 09, and 0A through 0Z. Values 0A through 0Z are not mapped and are interpreted as alphabetic values.
Three-character release. The value is a three character representation of the release of the product. The first character represents the Version of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are mapped to numeric values 10 (A) through 35 (Z). The second character represents the Release of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are mapped to numeric values 10 (A) through 35 (Z). The third character represents the Modification of the product, and valid values range from 0 to 9, and A through Z. Values A through Z are not mapped and are interpreted as alphabetic values.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0C0C E | Release not valid. |
| CPF0C1E E | Error occurred during running of &1 API. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
API introduced: IBM® i 7.2