Handle CD-ROM Premastering State (QLPCDRST, QlpHandleCdState) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Current CD-ROM premastering state | Output | Binary(4) |
| 4 | Distribution set map identifier used | Output | Char(10) |
| 5 | Requested CD-ROM premastering state | Input | Binary(4) |
| 6 | Distribution set map identifier | Input | Char(10) |
| 7 | Option | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Service Program: QLPCDROM
Threadsafe: No
The Handle CD-ROM Premastering State (OPM, QLPCDRST; ILE, QlpHandleCdState) API allows you to do the following:
- Enable the job for CD-ROM premastering. (Note:
Premastering is the set of activities done in preparation for creating a master
image as a template for manufacturing a number of copies of a CD-ROM.)
When the job is in this state, all save operations (SAVOBJ, SAVLIB, SAVLICPGM, SAV, SAVDLO, SAVSYS, and so forth) result in information being stored away about the sizes of these tape files. This information is then used as input for the Generate CD-ROM Premastering Information (QLPCDINF, QlpGenCdPremasteringInfo) API when it generates the QDSETMAP byte-stream file. See the description of the Generate CD-ROM Premastering Information API for an explanation of the QDSETMAP byte-stream file. Also, the following occurs:
- During a SAVSYS operation, special files are saved to tape that are needed on the CD-ROM when you try to perform an installation.
- Tape-write error protection is turned off during the save operations.
- Disable the job for CD-ROM premastering
Place the job back into a state where all save operations work as before. There are two options that can be used when disabling the job for CD-ROM premastering.
- Leave the current information about the files saved during this job as is.
This option gives you the ability to enable the job again later to continue save operations for a given set of CD-ROMs.
Signing off or ending your job is equivalent to performing this option.
- Erase the current information about the files saved during this job.
This option removes all existing information about any save operations done during this job. The next time you enable your job for CD-ROM premastering, there will be no information about this set CD-ROMs.
- Leave the current information about the files saved during this job as is.
- Query the current CD-ROM premastering job state
Authorities and Locks
- API Public Authority
- *EXCLUDE
- QSYS Library Authority
- *CHANGE
- User Space Authority
- *CHANGE
- User Space Library Authority
- *USE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that receives the generated list and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name.
The following special value is allowed for the user space name:
*NONE No information about tape files that are saved when a job was enabled for CD-ROM premastering are returned.
The following special values are allowed for the library name:
*CURLIB The current library is used to locate the user space. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the user space. This parameter must be blank when the requested CD-ROM premastering state parameter is not -1.
- Format name
- INPUT; CHAR(8)
The content and format of the information returned.
The possible format name follows:
TPFL0100 The list of tape files that are saved when the job was enabled for CD-ROM premastering For more information, see TPFL0100 List Data Section. This parameter must be blank when the requested CD-ROM premastering state parameter is not -1.
- Current CD-ROM premastering state
- OUTPUT; BINARY(4)
The variable that receives the current CD-ROM premastering state.
The possible values follow:
0 The job is not enabled for CD-ROM premastering 1 The job is enabled for CD-ROM premastering
- Distribution set map identifier used
- OUTPUT; CHAR(10)
The variable that receives the distribution set map identifier for the set of tapes currently being premastered.
- Requested CD-ROM premastering state
- INPUT; BINARY(4)
The CD-ROM premastering state that the job should be set to.
The possible values follow:
0 Disable the job for CD-ROM premastering without destroying the information about the tape files that have been saved. 1 Enable the job for CD-ROM premastering. 2 Disable the job for CD-ROM premastering and also destroy all information about tape files that have been saved. -1 Return the current CD-ROM premastering job state and the distribution set map identifier that are being used in the output parameters.
- Distribution set map identifier
- INPUT; CHAR(10)
The distribution set map identifier that uniquely establishes this set of CD-ROMs being premastered.
This name can only include the following characters:
- Uppercase characters (A-Z)
- Numeric characters (0-9)
- Underscore character (_)
This parameter must be blank when the requested CD-ROM premastering state parameter is not 1.
- Option
- INPUT; BINARY(4)
Whether to create new information about this particular set of CD-ROMs or to add information to a set of CD-ROMs. This parameter must be 0 when the requested CD-ROM premastering state parameter is not 1.
The possible values follow:
0 Start over with new information about CD-ROM premastering. If existing information is found about this set of CD-ROMs, the information will be erased. 1 Add information about CD-ROM premastering. If existing information is found about this set of CD-ROMs, it continues to be used and any future save operations that are done during this job are added to it.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated List
The file member list consists of the following:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section:
- TPFL0100 format
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name specified |
| 28 | 1C | BINARY(4) | Requested CD-ROM premastering state |
| 32 | 20 | BINARY(4) | Option |
| 36 | 24 | CHAR(10) | Distribution set map identifier |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
TPFL0100 List Data Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(17) | Tape file label |
Field Descriptions
Distribution set map identifier. The distribution set map identifier that was specified in the call to the API.
Format name specified. The format name that was passed to this API on the call in the format name parameter.
Option. The option that was passed to this API on the call in the option parameter.
Requested CD-ROM premastering state. The requested CD-ROM premastering state that was specified in the call to the API.
Tape file label. The name of the tape file that was saved to tape.
User space library name specified. The name of the user space library as specified on the call to the API.
User space library name used. The actual name of the library where this user space was found.
User space name specified. The name of the user space as specified on the call to the API.
User space name used. The actual name of the user space used to store the data listed.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3D9B E | Requested CD-ROM premastering state not valid. |
| CPF3D9C E | Option &1 not valid. |
| CPF3D9E E | Distribution set map identifier &1 is not valid. |
| CPF3DA2 E | &1 parameter is not blank. |
| CPF3DA3 E | &1 parameter is not 0. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R6